We’d like this to be a community driven project, so all kinds of input are welcome!
There are numerous way you could contribute:
Report bugs by submitting issues
Request features by submitting issues
Write examples and improve documentation
Contribute code: bug fixes, new features
This document is loosely based on the Contributing to xarray guide. It’s worth reading, it covers many of the subjects below in greater detail.
You can report bugs on the Issues pages. Please include a self-contained Python snippet that reproduces the problem. In the majority of cases, a Minimal, Complete, and Verifiable Example (MCVE) or Minimum Working Example (MWE) is the best way to communicate the problem and provide insight. Have a look at this stackoverflow article for an in-depth description.
We use Git for version control. Git is excellent software, but it might take some time to wrap your head around it. There are many excellent resources online. Have a look at the extensive manual online, a shorter handbook, searchable GitHub help, a cheatsheet, or try this interactive tutorial.
We use Black for automatic code formatting. Like Black, we are
uncompromising about formatting. Continuous Integration will fail if
black . from within the repository root folder would make
any formatting changes.
Integration black into your workflow is easy. Find the instructions here. If you’re using VisualStudioCode (which we heartily recommend), consider enabling the Format On Save option – it’ll save a lot of hassle.
If you add functionality or fix a bug, always add a test. For a new feature, you’re testing anyway to see if it works… you might as well clean it up and include it in the test suite! In case of a bug, it means our test coverage is insufficient. Apart from fixing the bug, also include a test that addresses the bug so it can’t happen again in the future.
pytest to do automated testing. You can run the test suite
locally by simply calling
pytest in the project directory.
pytest will pick up on all tests and run them automatically. Check
the pytest documentation, and have a look at the test suite to figure
out how it works.
Create a branch, and send a merge or pull request. Your code doesn’t have to be perfect! We’ll have a look, and we will probably suggest some modifications or ask for some clarifications.
How to release a new version¶
Update the Changelog.
Tag in Gitlab UI. Old tags are here. Old releases are here. To make a tag show up under releases, fill in the release notes in the UI. Since we keep changes in the Changelog only, just put
See https://imod.xyz/changelog.htmlin both the
Release notesbox. The tag name should be
vx.y.z, where x, y and z are version numbers according to Semantic Versioning.
git fetch --tagsand
git pull, verify you are on the commit you want to release, and that it is clean.
distfolders if present.
Create a wheel under
python setup.py bdist_wheel
Create a source distribution under
python setup.py sdist
Upload the files from step 5 and 6 to PyPI with
twine upload dist/*
Debugging Continuous Integration¶
Continuous Integration runs on an image with a specific operating system, and Python installation. Due to system idiosyncrasies, CI failing might not reproduce locally. If an issue requires more than trial-and-error changes, Docker is likely the easiest way to debug.
On windows, install Docker: https://docs.docker.com/docker-for-windows/install/
Pull the CI image (at the time of writing), and run it interactively:
docker pull continuumio/miniconda3:latest docker run -it continuumio/miniconda3
This should land you in the docker image. Next, we reproduce the CI setup steps. Some changes are required, such as installing git and cloning the repository, which happens automatically within CI.
apt-get update -q -y apt-get install -y build-essential conda update -n base conda conda install git cd /usr/src git clone https://gitlab.com/deltares/imod/imod-python.git cd imod-python conda env create -f environment.yml source activate imod pip install -e . curl -O -L https://gitlab.com/deltares/imod/imod-python/uploads/947a1e194a02ade1376d1111327db34d/mf6.gz gunzip mf6.gz chmod +x mf6 mv mf6 /opt/conda/envs/imod/bin
At this point, everything should be ready to run the tests on the Docker image.