Contribution Guidelines

The project practices test-driven development in Git feature (topic) branches. Please maintain a linear commit history by rebasing changes on the latest HEAD of the main branch before submitting them for review as a GitHub pull request.

Development Environment

Guidance

The application REQUIRES Git and Node.js 18 or newer. Building this documentation additionally REQUIRES GNU Make and Python 3.13 or newer.

Additionally, on Linux it needs lsb-release. On macOS it uses the Command Line Tools for Xcode and MacPorts. Several of the available make targets are listed below. Review the makefile for additional details.

make build-deps

Install the remaining system-level build dependencies. Requires root access via sudo.

make setup

Create (or update) a Python virtual environment named .venv in the project root directory and perform an editable installation of this project that includes development and testing tools.

make pre-commit

Configure optional pre-commit hooks, which require the virtual environment to be active in your code editor or Git porcelain.

make lint

Check code syntax and style.

make html

Build a preview of this documentation into build/html.

make docs

Build the versioned, multi-language documentation site into build/docs, one copy per Git release tag.

make clean

Reset the development environment, which includes removing the pre-commit hooks.

Code Style

Guidance

Changes MUST be self-contained and buildable, with updated tests and documentation.

This project follows these code styles:

Commit Messages

Guidance

This project REQUIRES Conventional Commits 1.0.0, with which it implements Semantic Versioning 2.0.0.

In commit messages:

  • Please use English.

  • Limit the first line to at most 100 characters. Wrap the rest of the commit message at column 70.

  • Summarize the changes with a one-sentence commit description in the imperative mood, lowercasing the starting verb and omitting ending punctuation.

  • For the commit type, specify one of build, chore, ci, docs, feat, fix, perf, style, refactor, revert, or test.

Commit messages are checked by commitlint via the commit-msg pre-commit hook; see .commitlintrc.cjs.

Commit Scopes

Guidance

Per Conventional Commits, a commit scope is an OPTIONAL abbreviation, acronym, codename, or keyword that provides additional context to reviewers by naming the essential component of the change. Changes covering multiple scopes or changes not specific to one scope MUST NOT specify a scope.

An atomic commit can alter multiple files. For example, an interface change could require modifications to class definitions, method calls, property references, and unit tests throughout the project. The commit scope tells reviewers where to focus their analysis. In change logs, commit scopes help sponsors understand the structure of the work going into fixes, features, or breaking changes. However, no commit scopes are currently in use.

Commit Types

build

a change to the build system or external dependencies, e.g., the makefile

chore

a miscellaneous tooling or tool configuration change, e.g., the .gitignore file, or a change not covered by the other commit types

ci

a change to continuous integration/continuous delivery (CI/CD) processes, e.g., GitHub Actions

docs

a documentation-only change, including edits to in-line documentation and comments

feat

a new feature

fix

a bug fix

perf

a code change that improves performance

refactor

a code change that neither fixes a bug nor adds a feature

revert

a commit that reverts a previous commit

style

a change that only affects formatting, or a change related to the linter configuration

test

a new test or a correction to an existing test