Conventions

Commit messages

<type>(<scope>): <description>

[optional body]

Types

feat, fix, docs, style, refactor, test, chore, build, ci

Principles

Fine-grained commits — each commit is a single logical change
Context-free messages — state what the commit does, not the development story
No narrative — avoid “I tried X, then Y”; state the result
Bullet lists in the body, not prose paragraphs

Examples

feat(cluster): add worker node lifecycle commands

- sind create worker with --count, --image, --unmanaged flags
- sind delete worker with nodeset expansion
- Update sind-nodes.conf and reconfigure slurmctld for managed nodes

fix(probe): handle systemd degraded state as ready

- systemctl is-system-running returns "degraded" when non-critical
  units fail, which is expected in containers

AI-assisted commits

Commits written with substantial help from an AI coding tool carry a Co-Authored-By: trailer naming the tool:

fix(mesh): tolerate stopped DNS container when updating records

- ...

Co-Authored-By: Claude <noreply@anthropic.com>

Commits made by Anthropic’s Claude Code agent are additionally authored as Claude <noreply@anthropic.com>. Please follow the same convention in your contributions.

Code style

Standard Go conventions (gofmt, go vet)
Use testify for assertions (assert for non-fatal, require for fatal)
Strong types for Docker identifiers (ContainerName, NetworkName, etc.)
Error wrapping with fmt.Errorf("context: %w", err)

License headers

All Go source files include the SPDX header:

// SPDX-License-Identifier: LGPL-3.0-or-later

Pull requests

Target the next branch; main only moves at release
One logical change per PR
Include tests for new functionality
Ensure make lint, make test and make check-coverage pass
Follow the commit message conventions above