|
| 1 | +# Contributing |
| 2 | + |
| 3 | +First of all, thank you so much for contributing! 🎉 💯 |
| 4 | + |
| 5 | +This document contains guidelines on how to most effectively contribute within this repository. |
| 6 | + |
| 7 | +If you are stuck, please feel free to ask any questions or ask for help. |
| 8 | + |
| 9 | +## Code of conduct |
| 10 | + |
| 11 | +This project is governed by our [code of conduct](code_of_conduct.md). By participating, you are expected to uphold this code. |
| 12 | +Instances of abusive, harassing, or otherwise unacceptable behavior may be |
| 13 | +reported to community leaders responsible for enforcement. |
| 14 | +Please open a [new security advisory notice]({{ github_url }}/security/advisories/new) (using defaults or "n/a" where unable to fill in the form) to privately notify us of any incidents of this nature. |
| 15 | + |
| 16 | +## Development |
| 17 | + |
| 18 | +This project leverages development environments managed by [uv](https://docs.astral.sh/uv/). |
| 19 | +We use [pytest](https://docs.pytest.org/) for testing and [GitHub actions](https://docs.github.com/en/actions) for automated tests. |
| 20 | + |
| 21 | +### Development setup |
| 22 | + |
| 23 | +Perform the following steps to setup a Python development environment. |
| 24 | + |
| 25 | +1. [Install Python](https://www.python.org/downloads/) (we recommend using [`pyenv`](https://github.com/pyenv/pyenv) or similar) |
| 26 | +1. [Install uv](https://docs.astral.sh/uv/getting-started/installation/) |
| 27 | + |
| 28 | +### Linting |
| 29 | + |
| 30 | +Work added to this project is automatically checked using [pre-commit](https://pre-commit.com/) via [GitHub Actions](https://docs.github.com/en/actions). |
| 31 | +Pre-commit can work alongside your local [git with git-hooks](https://pre-commit.com/index.html#3-install-the-git-hook-scripts) |
| 32 | + |
| 33 | +After [installing pre-commit](https://pre-commit.com/#installation) within your development environment, the following command also can perform the same checks within your local development environment: |
| 34 | + |
| 35 | +```sh |
| 36 | +% pre-commit run --all-files |
| 37 | +``` |
| 38 | + |
| 39 | +We use these same checks within our automated tests which are managed by [GitHub Actions workflows](https://docs.github.com/en/actions/using-workflows). |
| 40 | +These automated tests generally must pass in order to merge work into this repository. |
| 41 | + |
| 42 | +### Testing |
| 43 | + |
| 44 | +Work added to this project is automatically tested using [pytest](https://docs.pytest.org/) via [GitHub Actions](https://docs.github.com/en/actions). |
| 45 | +Pytest is installed through the uv environment for this project. |
| 46 | +We recommend testing your work before opening pull requests with proposed changes. |
| 47 | + |
| 48 | +You can run pytest on your work using the following example: |
| 49 | + |
| 50 | +```sh |
| 51 | +% uv run pytest |
| 52 | +``` |
| 53 | + |
| 54 | +## Making changes to this repository |
| 55 | + |
| 56 | +We welcome anyone to use [GitHub issues](https://docs.github.com/en/issues/tracking-your-work-with-issues/about-issues) (requires a GitHub login) or create [pull requests](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests) (to directly make changes within this repository) to modify content found within this repository. |
| 57 | + |
| 58 | +Specifically, there are several ways to suggest or make changes to this repository: |
| 59 | + |
| 60 | +1. Open a GitHub issue: {{ github_url }}/issues |
| 61 | +1. Create a pull request from a forked branch of the repository |
| 62 | + |
| 63 | +### Creating a pull request |
| 64 | + |
| 65 | +### Pull requests |
| 66 | + |
| 67 | +After you’ve decided to contribute code and have written it up, please file a pull request. |
| 68 | +We specifically follow a [forked pull request model](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/creating-a-pull-request-from-a-fork). |
| 69 | +Please create a fork of this repository, clone the fork, and then create a new, feature-specific branch. |
| 70 | +Once you make the necessary changes on this branch, you should file a pull request to incorporate your changes into this (fork upstream) repository. |
| 71 | + |
| 72 | +The content and description of your pull request are directly related to the speed at which we are able to review, approve, and merge your contribution. |
| 73 | +To ensure an efficient review process please perform the following steps: |
| 74 | + |
| 75 | +1. Follow all instructions in the [pull request template]({{ github_url }}/blob/main/.github/PULL_REQUEST_TEMPLATE.md) |
| 76 | +1. Triple check that your pull request is adding _one_ specific feature or additional group of content. |
| 77 | + Small, bite-sized pull requests move so much faster than large pull requests. |
| 78 | +1. After submitting your pull request, ensure that your contribution passes all status checks (e.g. passes all tests) |
| 79 | + |
| 80 | +Pull request review and approval is required by at least one project maintainer to merge. |
| 81 | +We will do our best to review the code addition in a timely fashion. |
| 82 | +Ensuring that you follow all steps above will increase our speed and ability to review. |
| 83 | +We will check for accuracy, style, code coverage, and scope. |
| 84 | + |
| 85 | +## Versioning |
| 86 | + |
| 87 | +We use [`setuptools-scm`](https://github.com/pypa/setuptools-scm) to help version this software through [`PEP 440`](https://peps.python.org/pep-0440/) standards and [semver.org](https://semver.org/) standards. |
| 88 | +Configuration for versioning is found within the `pyproject.toml` file. |
| 89 | +All builds for packages include dynamic version data to help label distinct versions of the software. |
| 90 | +`setuptools-scm` uses `git` tags to help distinguish version data. |
| 91 | +We also use the `_version.py` file as a place to persist the version data for occaissions where the `git` history is unavailable or unwanted (this file is only present in package builds). |
| 92 | +Versioning for the project is intended to align with GitHub Releases which provide `git` tag capabilities. |
| 93 | + |
| 94 | +### Releases |
| 95 | + |
| 96 | +We publish source code by using [GitHub Releases](https://docs.github.com/en/repositories/releasing-projects-on-github/about-releases) available [here]({{ github_url }}/releases). |
| 97 | + |
| 98 | +#### Release Publishing Process |
| 99 | + |
| 100 | +Several manual and automated steps are involved with publishing releases. |
| 101 | +See below for an overview of how this works. |
| 102 | + |
| 103 | +Notes about [semantic version](https://en.wikipedia.org/wiki/Software_versioning#Semantic_versioning) (semver) specifications: version specifications are controlled through [`setuptools-scm`](https://github.com/pypa/setuptools-scm) to create version data based on [git tags](https://git-scm.com/book/en/v2/Git-Basics-Tagging) and commits. |
| 104 | +Release git tags are automatically applied through [GitHub Releases](https://docs.github.com/en/repositories/releasing-projects-on-github/about-releases) and related inferred changes from [`release-drafter`](https://github.com/release-drafter/release-drafter). |
| 105 | + |
| 106 | +1. Open a pull request and use a repository label for `release-<semver release type>` to label the pull request for visibility with [`release-drafter`](https://github.com/release-drafter/release-drafter). |
| 107 | +1. On merging the pull request for the release, a [GitHub Actions workflow](https://docs.github.com/en/actions/using-workflows) defined in `draft-release.yml` leveraging [`release-drafter`](https://github.com/release-drafter/release-drafter) will draft a release for maintainers. |
| 108 | +1. The draft GitHub release will include a version tag based on the GitHub PR label applied and `release-drafter`. |
| 109 | +1. Make modifications as necessary to the draft GitHub release, then publish the release (the draft release does not normally need additional modifications). |
| 110 | +1. On publishing the release, another GitHub Actions workflow defined in `publish-pypi.yml` will run to build and deploy the Python package to PyPI (utilizing the earlier modified `pyproject.toml` semantic version reference for labeling the release). |
| 111 | + |
| 112 | +## Documentation |
| 113 | + |
| 114 | +Documentation for this project is published using [Sphinx](https://www.sphinx-doc.org) with markdown and Jupyter notebook file compatibility provided by [myst-parser](https://myst-parser.readthedocs.io/en/latest/) and [myst-nb](https://myst-nb.readthedocs.io/en/latest/) to create a "documentation website" (also known as "docsite"). |
| 115 | +The docsite is hosted through [GitHub Pages](https://pages.github.com/) and deployed through automated [GitHub Actions](https://docs.github.com/en/actions) jobs which trigger on pushes to the main branch or the publishing of a new release on GitHub. |
| 116 | +Documentation is versioned as outlined earlier sections covering versioning details to help ensure users are able to understand each release independently of one another. |
| 117 | + |
| 118 | +It can sometimes be useful to test documentation builds locally before proposing changes within a pull request. |
| 119 | +See below for some examples of how to build documentation locally. |
| 120 | + |
| 121 | +```shell |
| 122 | +# build single-version sphinx documentation |
| 123 | +# (useful for troubleshooting potential issues) |
| 124 | +uv run sphinx-build docs/src docs/build |
| 125 | + |
| 126 | +# build multi-version sphinx documentation |
| 127 | +# (used in production) |
| 128 | +uv run sphinx-multiversion docs/src docs/build |
| 129 | +``` |
0 commit comments