Contributor Guide

Thank you for your interest in improving this project. This project is open-source under the MIT license and highly welcomes contributions in the form of bug reports, feature requests, and pull requests.

Here is a list of important resources for contributors:

How to report a bug

Report bugs on the Issue Tracker.

How to request a feature

Request features on the Issue Tracker.

How to set up your development environment

You need Python 3.10+ and Poetry.

Install the package with all development requirements:

$ make install

Install the pre-commit hooks (runs automatically on git commit):

$ pre-commit install

You can now run an interactive Python session or the CLI:

$ poetry run python
$ poetry run spectrum_fundamentals

How to test the project

Run the full test suite:

$ make test

Run tests with a coverage report:

$ make coverage

Unit tests are located in the tests directory and are written using the pytest testing framework.

How to lint and format code

Auto-fix formatting and style issues:

$ make format

Check without modifying files (what CI runs):

$ make lint

Run static type checking:

$ make type-check

Run all CI checks locally

Before opening a pull request, run the same checks that CI will run:

$ make check

This is equivalent to make lint && make type-check && make test.

How to build and view the documentation

Build the docs:

$ make docs

Build and serve with live reload:

$ make docs-serve

The generated HTML files are in docs/_build/html/.

How to submit changes

Open a pull request to submit changes to this project against the development branch.

Your pull request needs to meet the following guidelines for acceptance:

  • The CI test suite must pass without errors and warnings.

  • Include unit tests. This project maintains a high code coverage.

  • If your changes add functionality, update the documentation accordingly.

It is recommended to open an issue before starting work on anything. This will allow a chance to talk it over with the owners and validate your approach.

How to make a release

Releases are published to PyPI automatically when a GitHub Release is published. The version string lives only in pyproject.toml — __version__ is read from the installed package metadata at runtime.

Release Drafter continuously updates a draft GitHub Release with an accumulated changelog from merged PR labels and a suggested next version (e.g. 0.9.1). It is a changelog generator — it never modifies any file in the repository.

Branch model: development is the integration branch; main mirrors exactly what is published on PyPI. The release tag is created on development and subsequently merged into main.

  1. Check the draft release on GitHub to see the suggested next version (e.g. 0.10.0). The version is inferred automatically from the labels on merged PRs since the last release.

  2. Bump the version on development:

    $ git checkout development && git pull
$ poetry version <next-version>   # e.g. poetry version 0.10.0
$ git add pyproject.toml
$ git commit -m "bump version to $(poetry version -s)"
$ git push origin development

  3. Publish the draft release on GitHub. The draft already targets development (set via commitish: development in .github/release-drafter.yml), so no target branch change is needed. Clicking Publish release triggers the publish workflow, which:

    • Re-runs the full CI suite as a hard gate.

    • Builds the wheel and sdist with poetry build.

    • Publishes to PyPI via OIDC Trusted Publishing (no secrets required).

    • Creates the tag v<next-version> on development.

  4. Merge the tagged commit into main so that main reflects the release:

    $ git checkout main && git pull
$ git merge v<next-version> --no-ff -m "release: v<next-version>"
$ git push origin main