How to contribute

Issue Tracker

We use the GitHub issue tracker for individual issues and the GitHub Projects page can give you a quick overview.

If you found a bug or you are missing a feature, please check the existing issues and then open a new one or contribute to the existing issue.

Development procedure

We use the standard GitHub workflow.

If you are not part of the cta-observatory organization, you need to fork the repository to contribute. See the GitHub tutorial on forks if you are unsure how to do this.

  1. When you find something that is wrong or missing

    • Go to the issue tracker and check if an issue already exists for your bug or feature

    • In general it is always better to anticipate a PR with a new issue and link the two

  2. To work on a bug fix or new feature, create a new branch, add commits and open your pull request

    • If you think your pull request is good to go and ready to be reviewed, you can directly open it as normal pull request.

    • You can also open it as a “Draft Pull Request”, if you are not yet finished but want to get early feedback on your ideas.

    • Especially when working on a bug, it makes sense to first add a new test that fails due to the bug and in a later commit add the fix showing that the test is then passing. This helps understanding the bug and will prevent it from reappearing later.

    • Create a changelog entry in docs/changes, please note the README.md there. Minor changes (on the magnitude of fixing a broken link or renaming a variable) can receive the no-changelog-needed label. This should, however, be a rare exception.

  3. Wait for review comments and then implement or discuss requested changes.

We use Github Actions to run the unit tests and documentation building automatically for every pull request. Passing unit tests and coverage of the changed code are required for all pull requests.

Running the tests and looking at coverage

For more immediate feedback, you should run the tests locally before pushing, as builds on travis take quite long.

To run the tests locally, make sure you have the tests extras installed and then run

$ pytest -v

To also inspect the coverage, run

$ pytest --cov=pyirf --cov-report=html -v

This will create a coverage report in html form in the htmlcov directory, which you can serve locally using

$ python -m http.server -d htmlcov

After this, you can view the report in your browser by visiting the url printed to the terminal.

Building the documentation

This documentation uses sphinx and restructured text. For an Introduction, see the Sphinx documentation.

To build the docs locally, enter the docs directory and call:

make html

Some changes require a full remake of the documentation, for that call

make clean html

If you created or deleted file or submodule, you also need to remove the api directory, it will be regenerated automatically.

Make sure the docs are built without warnings from sphinx, as these will be treated as errors in the build in the CI system as they most often result in broken styling.

To look at the docs, use

$ python -m http.server _build/html

and visit the printed URL in your browser.

Making your contribution visible

Together with the changes that will come with you PR, you should check that the following maintenance files are up-to-date:

  • .mailmap

  • CODEOWNERS

  • .zenodo.json

Further details

Please also have a look at the