Contributing#
Environment Setup#
pipx
This documentaion uses pipx to
install and manage non-project command line tools like hatch and
pre-commit. If you don't already have pipx installed, make sure to
see their documentation.
If you prefer not to use pipx, you can use pip instead.
-
Install hatch
pre-commit
Hatch will attempt to set up pre-commit hooks for you using pre-commit. If you don't already, make sure to install pre-commit as well:
pipx install pre-commit -
Build the Virtual Environment
-
If you need to, you can link a hatch virtual environment to your IDE. They can be located by name with the
env findcommand: -
Activate the Virtual Environment
Using Hatch#
Hatch Cheat Sheet#
| Command Description | Command | Notes |
|---|---|---|
| Run Formatting | hatch run lint:fmt |
Runs ruff code formatter |
| Run Linting | hatch run lint:all |
Runs ruff and mypy linters / type checkers |
| Run Type Checking | hatch run lint:typing |
Runs mypy type checker |
| Serve the Documentation | hatch run docs:serve |
Serve the documentation using MkDocs |
Run the pre-commit Hooks |
hatch run lint:precommit |
Runs the pre-commit hooks on all files |
Hatch Explanation#
Hatch is a Python package manager. It's most basic use is as a standardized build-system. However, hatch also has some extra features which this project takes advantage of. These features include virtual environment management and the organization of common scripts like linting and testing. All the operations in hatch take place in one of its managed virtual environments.
Hatch has a variety of environments, to see them simply ask hatch:
Syncing environment plugin requirements
Standalone
┏━━━━━━━━━┳━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━┓
┃ Name ┃ Type ┃ Dependencies ┃ Scripts ┃
┡━━━━━━━━━╇━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━┩
│ default │ pip-compile │ │ cov │
│ │ │ │ test │
├─────────┼─────────────┼──────────────────────┼─────────────┤
│ docs │ pip-compile │ markdown-callouts │ build │
│ │ │ markdown-exec │ cov │
│ │ │ mkdocs │ gh-deploy │
│ │ │ mkdocs-click │ serve │
│ │ │ mkdocs-gen-files │ test │
│ │ │ mkdocs-literate-nav │ │
│ │ │ mkdocs-material │ │
│ │ │ mkdocs-section-index │ │
│ │ │ mkdocstrings │ │
│ │ │ mkdocstrings-python │ │
│ │ │ pymdown-extensions │ │
├─────────┼─────────────┼──────────────────────┼─────────────┤
│ gen │ virtual │ │ lock-all │
│ │ │ │ release │
│ │ │ │ upgrade-all │
├─────────┼─────────────┼──────────────────────┼─────────────┤
│ lint │ pip-compile │ mypy>=1.6.1 │ all │
│ │ │ ruff~=0.1.4 │ fmt │
│ │ │ │ precommit │
│ │ │ │ style │
│ │ │ │ typing │
├─────────┼─────────────┼──────────────────────┼─────────────┤
│ test │ pip-compile │ pytest │ cov │
│ │ │ pytest-cov │ test │
│ │ │ pytest-xdist │ │
│ │ │ tomlkit │ │
└─────────┴─────────────┴──────────────────────┴─────────────┘
Matrices
┏━━━━━━━━━━┳━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━┳━━━━━━━━━┓
┃ Name ┃ Type ┃ Envs ┃ Dependencies ┃ Scripts ┃
┡━━━━━━━━━━╇━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━╇━━━━━━━━━┩
│ matrix │ pip-compile │ matrix.py3.8 │ pytest │ cov │
│ │ │ matrix.py3.9 │ pytest-cov │ test │
│ │ │ matrix.py3.10 │ pytest-xdist │ │
│ │ │ matrix.py3.11 │ tomlkit │ │
│ │ │ matrix.py3.12 │ │ │
├──────────┼─────────────┼─────────────────┼──────────────┼─────────┤
│ versions │ pip-compile │ versions.1.7.x │ │ cov │
│ │ │ versions.1.8.x │ │ test │
│ │ │ versions.1.9.x │ │ │
│ │ │ versions.1.10.x │ │ │
│ │ │ versions.1.11.x │ │ │
│ │ │ versions.1.12.x │ │ │
└──────────┴─────────────┴─────────────────┴──────────────┴─────────┘
That above command will tell you that there are four environments that you can use:
defaultdocsgenlint
Each of these environments has a set of commands that you can run. To see the commands for a specific environment, run:
Here we can see that the default environment has the following commands:
covcov-reporttesttest-cov
The one that we're interested in is cov, which will run the tests
for the project.
Since cov is in the default environment, we can run it without
specifying the environment. However, to run the serve command in the
docs environment, we need to specify the environment:
You can see what scripts are available using the env show command
Standalone
┏━━━━━━┳━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━┓
┃ Name ┃ Type ┃ Dependencies ┃ Scripts ┃
┡━━━━━━╇━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━┩
│ docs │ pip-compile │ markdown-callouts │ build │
│ │ │ markdown-exec │ cov │
│ │ │ mkdocs │ gh-deploy │
│ │ │ mkdocs-click │ serve │
│ │ │ mkdocs-gen-files │ test │
│ │ │ mkdocs-literate-nav │ │
│ │ │ mkdocs-material │ │
│ │ │ mkdocs-section-index │ │
│ │ │ mkdocstrings │ │
│ │ │ mkdocstrings-python │ │
│ │ │ pymdown-extensions │ │
└──────┴─────────────┴──────────────────────┴───────────┘
Committing Code#
This project uses pre-commit to run a set of checks on the code before it is committed. The pre-commit hooks are installed by hatch automatically when you run it for the first time.
This project uses semantic-versioning standards, managed by semantic-release.
Releases for this project are handled entirely by CI/CD via pull requests being
merged into the main branch. Contributions follow the gitmoji standards
with conventional commits.
While you can denote other changes on your commit messages with gitmoji, the following commit message emoji prefixes are the only ones to trigger new releases:
| Emoji | Shortcode | Description | Semver |
|---|---|---|---|
| 💥 | :boom: | Introduce breaking changes. | Major |
| ✨ | :sparkles: | Introduce new features. | Minor |
| 🐛 | :bug: | Fix a bug. | Patch |
| 🚑 | :ambulance: | Critical hotfix. | Patch |
| 🔒 | :lock: | Fix security issues. | Patch |
Most features can be squash merged into a single commit on a pull-request. When merging multiple commits, they will be summarized into a single release.
If you're working on a new feature, your commit message might look like:
Bug fix commits would look like this:
If you're working on a feature that introduces breaking changes, your commit message might look like:
Other commits that don't trigger a release might look like:
📝 Documentation Update Description
👷 CI/CD Update Description
🧪 Testing Changes Description
🚚 Moving/Renaming Description
⬆️ Dependency Upgrade Description
🎨 Non-Material Code Tidying Description
Pre-Releases#
semantic-release supports pre-releases. To trigger a pre-release, you
would merge your pull request into an alpha or beta branch.
Specific Release Versions#
In some cases you need more advanced control around what kind of release you
need to create. If you need to release a specific version, you can do so by creating a
new branch with the version number as the branch name. For example, if the
current version is 2.3.2, but you need to release a fix as 1.2.5, you
would create a branch named 1.2.x and merge your changes into that branch.
See the semantic-release documentation for more information about branch based releases and other advanced release cases.