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.
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
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 theREADME.md
there. Minor changes (on the magnitude of fixing a broken link or renaming a variable) can receive theno-changelog-needed
label. This should, however, be a rare exception.
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
ctapipe
development guidelinesThe Open Gamma-Ray Astronomy data formats which also describe the IRF formats and their definitions.
ctools
documentation page on IRFs