Contribution Guidelines

This project combines atomic commits, a linear commit history, and the Git feature branch workflow. Please rebase changes on the latest HEAD of the main branch before submitting them for review as a GitHub pull request.

Development Environment

This project requires Python 3.11 or newer. To set up your development environment on Linux or macOS, run these GNU Make commands from the project root directory.

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 clean

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

Additional targets are available, several of which are listed below. Review the makefile for details.

make lint

Check code syntax and style.

Code Style

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

This project implements Semantic Versioning 2.0.0 using Conventional Commits 1.0.0:

• Please use English in commit messages.

• The first line of the commit message SHOULD be at most 100 characters, while the rest of the commit message SHOULD be wrapped at column 70.

• The commit description SHOULD be an imperative sentence that summarizes the changes, with the starting verb in lower case and no ending punctuation.

• The commit type MUST be one of build, chore, ci, docs, feat, fix, refactor, or style.

Commit Scopes

An atomic commit can alter multiple files. For example, an interface change would require modifications the class definitions, method calls, and property references throughout the codebase. 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.

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

new content

fix

a content edit, e.g., correcting a grammar/spelling mistake or a factual error

refactor

an edit that neither makes corrections nor adds content

style

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