Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
94 lines (71 loc) · 5.55 KB

CONTRIBUTING.md

File metadata and controls

94 lines (71 loc) · 5.55 KB
Raw

Contributing

Contributions of all kinds are welcome. In particular, pull requests (PRs) are appreciated. The maintainers of this repository will help walk you through any issues in the pull request discussion, so please feel free to open a pull request even if you are new to pull requests.

Issues

The easiest contribution to make is to file an issue. Please perform a search of existing issues and provide clear instructions for how to reproduce a problem. If you have resolved an issue yourself, please contribute it to this repository so others can benefit from your work.

Please note that we cannot, in general, answer questions about particular connectivity measures and their merits. The user should be responsible for understanding the statistics they are using. Canonical papers for each connectivity measure are listed in the docstring of each connectivity measure. Questions and issues regarding implementation of the connectivity measures are welcome.

Code

Code contributions are always welcome, from simple bug fixes to new features. To contribute code:

  1. Please fork the project into your own repository and make changes there. Follow the Developer Installation instructions in the README to set up an environment with all the necessary software packages.
  2. Run code quality tools on your changes:
    • Format with ruff: ruff format spectral_connectivity/ tests/
    • Lint with ruff: ruff check spectral_connectivity/ tests/
    • Type check with mypy: mypy spectral_connectivity/
  3. Add tests for bugs/new features and make sure existing tests pass. Tests will run through GitHub Actions. For GPU-specific changes, also run SPECTRAL_CONNECTIVITY_ENABLE_GPU=true uv run --extra gpu pytest -m gpu on a CUDA machine.
  4. Add docstrings for each function in the numpy style.
  5. Add references if you are adding a connectivity measure.
  6. Update CHANGELOG.md with your changes under the "Unreleased" section.
  7. Submit a pull request.

If you are fixing a known issue, please add the issue number to the PR message.

If you are fixing a new issue, file an issue and then reference it in the PR.

How to build the documentation

  1. From the repository root, install the documentation dependencies with pip install -r docs/requirements-docs.txt.
  2. Run make -C docs html to build the site.
  3. Preview docs/_build/html/index.html. A commit to the master branch will automatically build the docs on Read the Docs.

How to make a release

This project uses an automated release workflow. To create a new release:

  1. Update CHANGELOG.md

    • Move changes from "Unreleased" section to a new version section
    • Use format: ## [X.Y.Z] - YYYY-MM-DD
    • Commit the changelog update

  2. Create and push a version tag (annotated)

    git tag -a vX.Y.Z -m "vX.Y.Z"
git push origin vX.Y.Z

  3. Automated workflow (.github/workflows/release.yml) Pushing the tag runs the release workflow, which automatically:

    • Runs code quality checks (ruff format, ruff check, mypy)
    • Runs tests on Python 3.10, 3.11, 3.12, and 3.13, plus the minimum dependency floors
    • Builds the source distribution and wheel and tests the built packages
    • Generates build-provenance attestations for the artifacts
    • Publishes to PyPI via trusted publishing (OIDC — no stored token), after approval in the protected pypi environment
    • Creates a GitHub release with notes extracted from CHANGELOG.md

    This is the only supported way to publish. Do not run twine upload by hand — a manual upload races the workflow and bypasses its tests, attestations, and approval gate. If the automated publish fails, fix the workflow (or PyPI trusted-publisher / environment settings) and re-run it. The one-time trusted-publishing and environment-protection setup is documented in docs/contributing.md.

  4. Conda release (requires anaconda and conda-build)

    First update conda-recipe/meta.yaml for the new release, or it will rebuild the previous version: set version to X.Y.Z and replace sha256 with the SHA-256 of the new PyPI sdist (from the release's "Download files" page, or openssl dgst -sha256 spectral_connectivity-X.Y.Z.tar.gz). Commit that change. Then build and upload:

    conda build conda-recipe/ --output-folder ./conda-builds
anaconda upload ./conda-builds/noarch/spectral_connectivity-*.tar.bz2

Version Numbering

This project follows Semantic Versioning:

  • MAJOR version for incompatible API changes
  • MINOR version for new functionality in a backwards compatible manner
  • PATCH version for backwards compatible bug fixes

Authorship on manuscripts

Authorship on any manuscripts for the spectral_connectivity package will be granted based on substantive contributions to the design and implementation of the spectral_connectivity package. This is not solely determined by lines of code or number of commits contributed to the project, but these will be considered when making this decision. For example, a one letter correction in documentation will not be considered substantive for authorship (although typo correction is very much appreciated).