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

This project REQUIRES Git, GNU Make, and Python 3.12 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 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:

• Python Black and isort

• the Google Markdown style guide, but with a more traditional 70-character line limit

• the Home Assistant YAML style guide

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, or test.

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

Hint

Because this is a documentation project, only use the docs commit type when making changes to project meta-documentation such as README.md. Use the feat, fix, refactor, and style commit types to describe content edits.

feat

a new feature; for documentation projects, new content

fix

a bug fix; for documentation projects, a correction

perf

a code change that improves performance

refactor

a code change that neither fixes a bug nor adds a feature, or for documentation projects, an edit that neither makes a correction nor adds content

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