ADR-004 — Git and GitHub Conventions

Status

Accepted

Context

The project uses git with a GitHub repository and gh CLI for the workflow.

Decision

Commits — Simplified Conventional Commits:

<type>[(<scope>)]: <imperative description in English> [— <optional detail>]

Allowed types: feat, fix, chore, docs, refactor, test, style.

The optional (<scope>) narrows the area of change (e.g., org-chart, angular, auth). It is not required but helps readability in git log.

The separator for additional detail on the same line is — (space + em dash + space), not a comma or parentheses.

Valid examples:

feat: add employee FSM transition endpoint
feat(org-chart): render coverage bars per node
fix: correct coverage aggregation on partial units
fix(angular): handle 401 refresh race condition
docs: fill ADR-002-a backend dev stack
chore: remove unused migration file — leftover from branch merge

Branches — kebab-case with type prefix:

<type>/<short-slug>

Examples: feat/employee-fsm, fix/coverage-calc, docs/adr-stack, chore/cleanup-migrations.

main is the integration branch. There is no develop. Feature branches are created from main and merged via PR.

Pull Requests:

One PR per concern — do not mix unrelated feature + refactor + docs.
Title in the same format as a commit: feat: ..., fix: ....
Minimal body: one line of context and a list of relevant changes.
Merge strategy: squash merge for small features; merge commit when the granular branch history adds value.

Tags and versions:

Follow semver (v0.1.0, v1.0.0). Managed with the kdx-version skill and documented in CHANGELOG.md.

Consequences

Any git log --oneline is readable and filterable by type without additional tools.
ADRs and the PRD can reference commits by type (feat:, fix:) instead of by hash when the hash is not relevant.
Commitizen, commitlint, and automatic validation hooks are not adopted — the convention is simple enough to follow without mechanical enforcement.