.. SPDX-FileCopyrightText: © 2024 the IceTray contributors .. SPDX-License-Identifier: BSD-2-Clause .. highlight: console 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? **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 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. 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 :ref:`testingguide-main`. * `Python unittest docs `_ 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 :ref:`documentation-main`. 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.