Developer Guide#
Getting Started for Developers#
Warning
The following guide is used only if you want to develop the CTLearn package, if you just want to write code that uses it as a dependency, you can install CTLearn from PyPI. See User Guide.
Installation for Developers#
As a developer, clone the repository and install CTLearn in development mode. We support two methods: pip/venv and Pixi.
Install Pixi if needed, then clone the repository and install the development environment:
$ git clone https://github.com/ctlearn-project/ctlearn.git
$ cd ctlearn
$ pixi install -e dev
Useful commands from the repository directory:
$ pixi run -e dev test # run the test suite
$ pixi run -e test-py313 test # run tests with Python 3.13
$ pixi run -e test-py314 test # run tests with Python 3.14
$ pixi run -e dev make -C docs html
$ pixi shell -e dev # open a shell in the dev environment
$ pixi clean # remove Pixi environments
Pixi targets Linux x86_64 and Apple Silicon macOS.
$ git clone https://github.com/ctlearn-project/ctlearn.git
$ cd ctlearn
$ python -m venv .venv
$ source .venv/bin/activate
$ python -m pip install --upgrade pip
$ python -m pip install -e ".[dev]"
Contributing to CTLearn#
CTLearn is open source and welcomes contributions from the community! CTLearn follows the same code style and development guidelines as the ctapipe community. We recommend reviewing the ctapipe Developer Guide in detail and following the guidelines below:
Contributing guidelines#
In CTLearn we follow the “fork-and-pull” Git workflow:
Fork the repository on GitHub
Clone the project to your own machine
Commit your changes to your own branch
Push your work back up to your fork on GitHub
Submit a Pull Request so the core developer team can review your changes
Some CI features are unavailable for pull requests from forks. Frequent contributors and those preparing pull requests with significant changes can contact the maintainers to request write access and contribute from a branch in the main repository instead of a fork.
Code quality#
CTLearn uses pre-commit hooks for whitespace and file checks, spelling, and Ruff linting and formatting. Install the development dependencies and set up the hooks in your checkout with:
pip install -e ".[dev]"
pre-commit install
The hooks will run automatically before each commit. To run them manually on all files, use:
pre-commit run --all-files
CI also runs SonarQube analysis through SonarCloud on pull requests from this
repository. It checks code quality, including potential bugs, security issues,
maintainability, and test coverage.
Documentation builds#
For documentation-only pull requests, apply the documentation-only label
to skip the pip and Pixi test jobs and the dependent SonarCloud scan. The
documentation build still runs, as do the lint and data-cache jobs and any
other applicable workflow checks. Removing the label restores the skipped
pull request jobs. The label does not affect push builds, including pushes to
main and tags, or the release workflow.
To speed up a pull request’s documentation build, apply the
skip-docs-tutorials label. The documentation and tutorial pages are still
built, but the tutorials are not executed, so their outputs are omitted.
Removing the label restores tutorial execution. Push builds always execute the
tutorials, regardless of pull request labels.
Changelog entries#
Every pull request should include a Towncrier fragment describing its user-facing
changes. See docs/changes/README.md for the naming conventions and supported
categories. If a change does not warrant a changelog entry, maintainers can apply
the no-changelog-needed pull request label.
Issues#
Feel free to submit issues and enhancement requests through our issues page on GitHub.
Copyright and License#
CTLearn is licensed under the BSD 3-Clause License.
CTLearn does require that you make your contributions available under the BSD 3-Clause License in order for it be included in the main repository.
Core Dependencies#
The following list shows CTLearn’s most important dependencies and their minimum versions where specified. We recommend installing the latest releases.
python>=3.12torch>=2.4.0tensorflow>=2.18keras>=3.0astropyctapipe>=0.29.0dl1_data_handler>=0.14.13,<0.15.0numbanumpypandaspyyaml