Contributing¶
Contributions to DSF are welcome, including code, bug reports, feature requests, documentation improvements, tests, and scientific feedback.
DSF is developed within the LSST Dark Energy Science Collaboration, with contributions from the wider scientific community.
Development takes place in the DSF GitHub repository.
Before starting substantial development, please open an issue or contact the project maintainers to discuss and coordinate the proposed work.
Getting Involved¶
Reporting issues¶
Bug reports and feature requests can be submitted through the GitHub issue tracker.
Bug reports should include:
The expected behaviour.
The actual behaviour.
The DSF version or commit used.
Relevant environment details.
A minimal reproducible example, where possible.
Submitting pull requests¶
Code contributions can be submitted through a GitHub pull request.
Pull requests should explain what was changed, why the change is needed, and, where applicable, reference the corresponding issue.
New functionality should include appropriate tests and documentation.
Development¶
Setting up the environment¶
Install DSF together with its development dependencies from the repository root:
pip install --group dev -e .
DSF uses tox to manage development workflows.
List the available environments:
tox list
Run a specific environment:
tox -e <environment>
Testing¶
Tests are located in the tests directory.
New functionality and bug fixes should include tests covering the
added or changed behaviour.
Run tests for all supported Python versions:
tox -m test
Run tests for a specific Python version:
tox -e py312
Pass arguments directly to pytest after --:
tox -e py312 -- tests/test_example.py
Run the coverage workflow:
tox -e cov
Linting¶
DSF uses Ruff for linting and code-quality checks.
Run the linting workflow:
tox -e lint
Automatically fix supported linting errors:
tox -e lint -- --fix
Code style¶
Code should follow PEP 8 and the general docstring conventions in PEP 257.
All Python modules should include a module-level docstring describing their purpose.
Public classes, functions, and methods should include clear, concise Google-style docstrings.
Docstrings should describe the purpose and public interface rather than implementation details.
They should document parameters, return values, raised exceptions, and relevant scientific or numerical assumptions.
Documentation¶
Writing documentation¶
DSF documentation is written in reStructuredText and built with Sphinx.
New documentation pages should be added to the appropriate Sphinx
toctree.
Building documentation¶
Build the documentation with:
tox -e docs
On macOS, build the documentation, run doctests, and open the resulting pages in a browser:
tox -e do
Build the documentation for the main branch and release versions:
tox -e docs-releases
Generated documentation is written to docs/_build.