Contributing to IceTray¶
All members of the IceCube collaboration are encouraged to contribute to the development of IceTray. For some this process can be intimidating, this guide is intended to help you through the process.
We also encourage you to reach out for help and guidance as needed. Several good places to start are:
The IceCube IceTray docs. These are built regularly from source and available at: https://docs.icecube.aq/icetray/main
The IceCube software Slack channel. https://wiki.icecube.wisc.edu/index.php/Join_us_on_Slack
Local experts in your institution or group. Many institutions have local experts who can help you get started or when you are stuck.
GitHub¶
All software coordination, development, and issue tracking is done through dedicated repository on GitHub. The IceTray repository is a private repository, and to see it, you need to be a member of the IceCube organization on GitHub. If you are not a member, or have just joined GitHub, please take a look at the IceCube GitHub Guide for guidance on how to join, how to setup your account for use in IceCube, and more guidance on contributing to IceCube software.
GitHub Issues¶
Whether you found a bug, you want to request an enhancement, or you’re actively developing a new feature, GitHub Issues is a great place to keep everyone informed about what you’re working on. Click on
the label button to provide more info about your topic. Every time you make a relevant commit, remember to tag the issue (e.g.,
git commit -m 'progress on #12'
), and when you finish and issue you can close it with a commit too! (e.g., git commit -m
'Close #12'
)
Create a Pull Request¶
If you have a change you would like to make to the code please submit a pull request on GitHub. Please, follow the directions below to install for development and to make sure the pre-commit, unit-tests, and documentation are correct. Also make sure that your pull request’s title, description, and its included commits are descriptive before submitting.
As part of the PR review, the IceCube software team will review the code, and may ask for changes or improvements. We generally check for:
Code style and formatting - does the code follow our accepted styles, is it clear and readable?
Documentation - is the code well documented, both in the code, and in our docs system?
Tests - does any new code or bugfixes have tests to ensure that it works as expected?
Functionality - does the code do what it is supposed to do, and does it do it well?
Actions - does the code build, test, and pass all the checks in all our CI systems?
Formatting - Does the code style and format adhere to our standards, pass linters, and contain an SPDX license?
Note: Never merge your own pull request. It is a bad practice in a large development group. If you think your PR is ready to go and feel it is lingering too long, ask in #software on Slack. We often manage merging and testing as we run up to release and can prioritize some PRs over others.
pre-commit
¶
IceTray uses pre-commit which will run checks and automatic updates on the code before committing it to the repository. These checks will be run on every pull-request submitted to GitHub and ones that do not pass the checks will be rejected.
You need to verify that the pre-commit
checks will pass before you push or submit a pull-request.
pre-commit
may be installed through your Linux distribution’s package manager or it can
be installed with pip:
$ pip install pre-commit
Once installed, you will need to add pre-commit
’s hooks in the .git
directory.
pre-commit
can do this automatically by running the following command in the checkout directory:
$ pre-commit install
This will add a script to .git/hooks/pre-commit
which will be run before every commit.
You only need to do this once, after cloning IceTray.
At any time, you can run pre-commit
on all files without making a commit.
To do this you can simply run the following command:
$ pre-commit run --all
Currently the only check that is run is ruff, but more may be added in the future. Be sure that all checks pass before submitting a pull request.
ruff - Python linter¶
We use the ruff linter to check the python code for formatting, style and common errors. In addition to being part of our pre-commit checks, you can run it manually:
$ ruff check .
This will check all files. To reduce the number of files checked, try:
$ ruff check <path_to_a_single_python_file or directory>
The rules applied can vary from project to project, with some projects having more strict rules than others.
A generic set of rules is applied to all projects via IceTray’s pyproject.toml
file, but each project can override
this with their own.
Ruff has the ability to automatically fix some issues for you:
$ ruff check . --fix
A good reference for the rules that ruff applies can be found at ruff’s documentation. They have good explanations of the rules, and some good suggestions to address issues.
Licenses¶
We want to make sure all code in IceTray is properly licensed. We use the SPDX license system. Full details can be found in the docs.
Tests¶
IceTray has an extensive unit test suite and uses ctest as a test runner. Before
submitting any pull-request make sure that all the tests pass by running ctest
in your build directory. In since IceTray is
such a large and modular codebase, it is often only necessary to test the project you are altering and possibly other projects
which depend on that project. In that case you can run:
$ ctest -R myproject
where myproject
is a regular expression representing the projects you wish to test.
Writing tests¶
Tests can be added, either for C++ or Python. These links will help you with writing tests:
IceCube testing guidelines at Complete Testing Guide for IceCube.
New functionality or bugfixes should be accompanied by tests to ensure that the new code works as expected.
Documentation¶
If you modify the documentation, you should build it to make sure that it renders correctly, before it before submitting a pull request.
$ docs-build --projects myproject otherproject --no-doxygen --no-inspect --open
For more information on building the docs see Documentation.
Checking the GitHub Actions¶
After every pull request GitHub actions will automatically run the tests on a number of python versions and platforms, you can see the results at the GitHub actions page. Pull requests will not be merged unless all the relevant tests pass.