Contributing Guide#

The wradlib project encourages everyone to contribute to the developement of wradlib. This paper describes the general guidelines for contributing to wradlib. There is more information on wradlib’s community effort at the project’s main website wradlib.org.

In general wradlib uses GitHub Pull Requests for contribution. Second, the wradlib developers have GitHub Commit Access to the project’s main repository.

Code of Conduct#

Contributors to wradlib are expected to act respectfully toward others in accordance with the OSGeo Code of Conduct.

Contributions and Licensing#

All contributions shall comply to the project license.

GitHub#

Source code, testing, bug tracking as well as docs and wiki are handled via GitHub.

Documentation#

wradlib’s documentation source is contained in the docs-folder of the wradlib repository, and mainly written in myst markdown.
Jupyter Notebooks in examples/notebooks-folder are utilized to extend the documentation with examples and tutorials.
wradlib uses Sphinx and myst_nb to compile docs on readthedocs.org.

Issue tracking#

Using wradlib’s GitHub issue tracker users can file bug reports or discuss feature requests. Bug reports should contain used wradlib as well as Python and OS version, error messages and instructions to reproduce the bug.

Forking wradlib#

For this purpose, you need to have a GitHub Account and Git. Then fork wradlib, make changes and create a pull request.

Setup#

The Installation section will provide you with detailed guidance on how to install \(\omega radlib\) and the required dependencies for different operating systems (MS Windows, Linux, Mac OS). \(\omega radlib\) 2.8.1 has been tested with Mambaforge Python. It is available via conda-forge channel on linux-64, osx-64 and MS Windows 64 versions.

As a developer, though, you should rather link into \(\omega radlib\)’s version control. This way, it will be easier for you to track changes and to contribute your changes to \(\omega radlib\)’s main repository (see next section). Just install Git, then clone the \(\omega radlib\) repository to your local system by executing the following command in your shell:

$ git clone https://github.com/wradlib/wradlib.git

Contributing#

Everyone can contribute to the developement of \(\omega radlib\) by using the Fork and Pull model. For this purpose, you need to set up Git (see section Setup). Then start a Pull Request!

Step 1: Fork your own \(\omega radlib\) repository from the \(\omega radlib\) main repo.
Step 2: Implement your changes into the forked repository. Test your code.
Step 3: Now you want to feed these changes back into the main \(\omega radlib\) development branch? Start a Pull Request!
Step 4: We will review your changes. On approval, we will merge your fork back into the main \(\omega radlib\) branch.
Step 5: Now everyone can benefit from your improvements.

A step-by-step tutorial for a pull request can be found in the GitHub documentation.

Finally, you are welcome to contribute examples of your own \(\omega radlib\) applications in examples/notebooks.

Building documentation#

In order to build the documentation you need to satisfy a few more dependencies which are mainly related to Sphinx. These are specified in the readthedocs_environment.yml.

Once these requirements are met, you can open a console window within the wradlib-repository and execute sphinx-build -v -b html docs/ doc-build. This will give you the latest documentation under the wradlib/doc-build directory. Simply open the index.html file to view the documentation.

Testing#

\(\omega radlib\) uses the pytest framework. New functions should come with corresponding unittests in the wradlib/wradlib/tests directory. Just have a look at available tests to get an idea. In addition, examples and docstrings are a good way to combine testing and documentation. In the docstrings, the Examples section will be tested by our testing framework. This could look like this:

def foo(a):
    """Docstring to be evaluated by doctest

    Examples
    --------
    >>> from wradlib.some_module import foo
    >>> print(foo(3))
    4
    """
    return a + 1

Continuous Integration#

We use GitHub Actions for Continuous Integration (CI). CI means, in our case, that each commit pushed to \(\omega radlib\)’s main repository will trigger different test suites on the CI service. If all tests pass successfully, a new documentation will be built on https://readthedocs.org and published on https://docs.wradlib.org. In case a new release tag is associated with a commit, a new release will be distributed via PyPI.

Contributing Guide

Contents