Commit Guide¶

Commit Message Format¶

We follow the Conventional Commits specification. This enables automated semantic versioning and a readable changelog.

<type>(<scope>): <short summary>

[optional body]

[optional footer]

Types¶

Type	When to use	Version bump
`feat`	A new feature or capability	`minor`
`fix`	A bug fix	`patch`
`docs`	Documentation only changes	none
`refactor`	Code change that is neither a fix nor a feature	none
`chore`	Maintenance tasks, dependency updates, config changes	none
`ci`	Changes to CI/CD workflows	none
`revert`	Reverts a previous commit	`patch`

Any type with BREAKING CHANGE: in the footer triggers a major bump regardless of type.

Scope¶

The scope is optional but recommended. Use it to indicate what part of the platform is affected:

feat(harbor): add robot account for ci pipeline
fix(external-secrets): correct openbao path for kodexet cluster
docs(onboarding): add commit guide
chore(cert-manager): bump chart version to 1.14.0

Common scopes: component names (harbor, keycloak, cilium, metallb, etc.), cluster names (hetzner-mgmt, kodexet), or area (terraform, docs, ci).

Summary¶

Written in lowercase imperative mood: add, fix, update, remove — not added, fixes, updating
No period at the end
Max 72 characters

Body¶

Use the body to explain why, not what. The diff already shows what changed.

feat(external-secrets): add ClusterExternalSecret for harbor pull access

Previously each namespace required a manually created pull secret.
ClusterExternalSecret syncs the secret into all namespaces automatically,
removing the need for per-namespace manual steps when deploying new workloads.

Breaking Changes¶

Add BREAKING CHANGE: in the footer for anything that requires manual intervention after applying:

refactor(metallb): change IP pool name

BREAKING CHANGE: IPAddressPool renamed from default-pool to cluster-pool.
Existing LoadBalancer services may need to be recreated.

Commit Size¶

A commit should represent one logical change. Ask yourself: can this be described in a single conventional commit summary without using "and"?

Good — focused commits:

feat(harbor): add ClusterExternalSecret for image pull secret
fix(docs): correct service selector to match deployment label
chore(cert-manager): bump chart to v1.14.0

Bad — too broad:

feat: add harbor pull secret, fix docs service, update cert-manager and refactor metallb config

Rules of thumb¶

One component changed → one commit
One bug fixed → one commit, even if it touches multiple files
Unrelated changes → separate commits, even if small
Documentation update for a feature → include in the same commit as the feature, not a separate one

Smaller commits are easier to review, easier to revert, and produce a more useful Git history.