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:

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:

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.