Contributing

Disclaimer

Disclaimer

While this project is FOSS and you are welcome to use it, know that I am making this for myself. So do not expect any kind of support or updates or maintenance or longevity. Caveat Emptor.

With that said, if you still want to try contributing, then nothing is stopping you. And to that end (and for my future self), here is documented some helpful info on how this project is put together and developed.

Development Standards

This project follows the following standard practices:

• Conventional Commits 1.0.0 for commit messages.

  • If using VS Code, then the Conventional Commits extension is recommended.

  • If committing from the terminal, use cz c instead of git commit.

• Semantic Versioning 2.0.0 for versioning.

• Keep a Changelog for the changelog.

• Make a README for the README

• REUSE SOFTWARE for licence and copyright information.

• Markdown for all documentation.

  • (with enhancements for use with mkdocs and various plugins.)

Developer Installation

1. Install Devbox.
   Currently testing against version 0.16.0.

2. Clone this repository.

3. Run:

devbox shell
init
check push
docs build
check --help

Installation Details

• Devbox is a tool for creating per-project development environments using Nix (not to be confused with NixOS). It is used in this project for non-Python dev tools and bootstrapping.

• On first run, devbox shell will download and install all the needed system tools for the environment

• On the first run, init will download and install the base Python version, needed commands, hooks, etc.

• pre-commit is a tool for running certain checks and fixes on the code before commits and/or pushes.

• NOTE: No commit, push or pull request should or will be accepted unless all pre-commit and pre-push hooks pass. No exceptions!

• Hatch is a tool for managing dependencies and virtual environments.

• The check command calls Hatch to perform common tasks, while also making it easier to do so.

• check push runs all common tasks like pre-commit checks, , security checks, licensing checks etc.

• On first run, check push will also download and install several files, etc.

• docs build is how to generate the documentation.

• The check command has several sub-commands to help you while developing. Check it out. 😺

• You can enter the default virtual environment with hatch shell.

What Tool Does What

Several of the development tools used in this project have overlapping capabilities. This section is an attempt clarify which tool is used for which common task.

Task	Tool
Install non-Python dev tools	Devbox (NIX)
Install Python dev tools	The init script (uv)
Install base/minimum Python version	The init script (uv)
Install pre-commit hooks	The init script (pre-commit)
Run pre-commit hooks manually	The check script (pre-commit)
Enter the default virtual environment	Hatch
Commit changes from the terminal	Commitizen (use cz c)
Update version on a release	Hatch
Generate the documentation	The docs script (Hatch, Mkdocs)
Pin project dependency versions	uv
Pin development dependency versions	uv
Format Markdown	pre-commit (markdownlint-cli2)
Format YAML	pre-commit (yamlfmt)
Format JSON	pre-commit (pretty-format-json)
Spell checking	pre-commit (codespell), docs (Mkdocs)
Remove all venvs, tools, caches, etc.	The clean script
Run CI pipeline	Github Actions (using the scripts above)