Contributing to res2df

Contributing to res2df is easiest on Linux computers. Windows has not been tested, and for Mac you will have to compile OPM yourself.

Getting started as a developer

The first thing to do, is to create a fork of res2df to your personal github account. Go to https://github.com/equinor/res2df and click the Fork button.

Clone your fork to your local computer:

git clone git@github.com:<youraccount>/res2df
cd res2df

Then add the upstream repository:

git remote add upstream git@github.com:equinor/res2df

This requires a valid login setup with SSH keys for you github account, needed for write access.

After cloning, you should make a Python virtual environment in which you install res2df and its dependencies. If you want to create a new virtual environment for res2df, you can do something like the following:

python3 -m venv venv-res2df
source venv-res2df/bin/activate

and then run pip :

pip install -e .[tests,docs]

to install res2df in “edit”-mode together will all dependencies for res2df, its test suite and documentation.

A good start is to verify that all tests pass after having cloned the repository, which you can do by running:

pytest

Getting started on Equinor Linux computers

On Equinor Linux computers, is is recommended to run with the Komodo environment, which will provide an analogue to virtualenv for making the virtual environment.

The git operations are the same as above.

Follow instructions on https://fmu-docs.equinor.com/docs/komodo/equinor_komodo_usage.html for activating a Komodo release, and perform the instructions for extending Komodo in order to prepare for the command:

pip install -e .[tests,docs]

NB: For every monthly Komodo release, you might have to remake your komodo-venv.

Using res2df without OPM

OPM is only pip-installable on Linux. To use the non-OPM dependent res2df modules on something else than Linux (but with resdata installed), you should install all the dependencies (except OPM) using pip (see setup.py for list of dependencies), and then install res2df with the --no-deps option to pip. After this, the non-OPM dependent modules should work, and others will fail with import errors.

Development workflow

If you have a feature or bugfix, a typical procedure is to:

  • Consider writing an issue on https://github.com/equinor/res2df/issues describing what is not working or what is not present.

  • Make a new git branch for your contribution, from an updated master branch.

  • Write a test for the feature or a test proving the bug. Verify that pytest now fails. Either append to an existing test-file in tests/ or make a new file.

  • Implement the feature, or fix the bug, and verify that pytest succeeds.

  • Consider if you should write RST documentation in docs/ in addition to docstrings.

  • Check your code quality with pylint. New code should aim for maximal pylint score. Pylint exceptions should only be used when warranted.

  • Commit your changes, remember to add any new files.

  • Push your branch to your fork on github, and go to github.com/equinor/res2df and make a pull request from your branch. Link your pull request to any relevant issue.

  • Fix any errors that pop up from automated checks.

  • Wait for or ask for a code review

  • Follow up your pull request by merging in changes from the master branch as other pull requests are being merged.

  • When your PR is ready for merge, it should usually be “squashed” into a single commit that is rebased on top of the current master.

Continuous integration

A pull request that has been pushed to Github will be subject to automatic testing, for code style, pytest and for documentation validity. If your code does not pass black or flake8 verification it will fail the CI workflows.

The exact requirements for CI can be deduced from files in .github/workflows/. The commands in these files can be run manually on your command line, and if they fail, you will have to fix before pushing your branch.

Some of the requirements can be added to your editor, but you can also integrate the tool pre-commit to your cloned copy in order to force certain checks to be in place before a commit is accepted. Issue the command pre-commit install in your copy to get started with this.

Writing documentation

Write good docstrings for each function, and use Google style for arguments. See https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html for specification.

Add RST (reStructuredText) documentation to files in the docs/ directory.

Your RST files must pass validity through the rstcheck tool. Use sphinx to build HTML documentation:

python setup.py build_sphinx

and check the generated HTML visually by running f.ex firefox:

firefox build/sphinx/html/index.html &