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.