Skip to content

Latest commit

 

History

History
81 lines (59 loc) · 3.04 KB

CONTRIBUTING.md

File metadata and controls

81 lines (59 loc) · 3.04 KB
Raw

Contributing

The following is a set of guidelines for contributing to ERT.

Ground Rules

  1. We use Black code formatting
  2. All code must be testable and unit tested.

Commits

We strive to keep a consistent and clean git history and all contributions should adhere to the following:

  1. All tests should pass on all commits(*)
  2. A commit should do one atomic change on the repository
  3. The commit message should be descriptive.

We expect commit messages to follow this style:

  1. Separate subject from body with a blank line
  2. Limit the subject line to 50 characters
  3. Capitalize the subject line
  4. Do not end the subject line with a period
  5. Use the imperative mood in the subject line
  6. Wrap the body at 72 characters
  7. Use the body to explain what and why vs. how

This list is taken from here.

Also, focus on making clear the reasons why you made the change in the first place—the way things worked before the change (and what was wrong with that), the way they work now, and why you decided to solve it the way you did. A commit body is required for anything except very small changes.

(*) Tip for making sure all tests pass, try out --exec while rebasing. You can then have all tests run per commit in a single command.

Pull Request Scoping

Ideally a pull request will be small in scope, and atomic, addressing precisely one issue, and mostly result in a single commit. It is however permissible to fix minor details (formatting, linting, moving, simple refactoring ...) in the vicinity of your work.

If you find that you want to do lots of changes that are not directly related to the issue you're working on, create a seperate PR for them so as to avoid noise in the review process.

Pull Request Process

  1. Work on your own fork of the main repo
  2. Squash/organize your work into meaningful atomic commits, if possible.
  3. Push your commits and make a draft pull request using the pull request template.
  4. Check that your pull request passes all tests.
  5. While you wait, carefully review the diff yourself.
  6. When all tests have passed and your are happy with your changes, change your pull request to "ready for review" and ask for a code review.
  7. As a courtesy to the reviewer(s), you may mark commits that react to review comments with fixup (check out git commit --fixup) rather than immediately squashing / fixing up and force pushing
  8. When the review is concluded
  • rebase onto base branch if necessary,
  • squash whatever still needs squashing, and
  • fast-forward merge.

Build documentation

You can build the documentation after installation by running

pip install ".[dev]"
sphinx-build -n -v -E -W ./docs ./tmp/ert_docs

and then open the generated ./tmp/ert_docs/index.html in a browser.

To automatically reload on changes you may use

sphinx-autobuild docs docs/_build/html