Conventional Commit & Branch Workflow
Enforce the repository's git conventions. All commit and branch text is English.
The integration branch defaults to dev; if the repo uses another name
(main, develop), ask once and reuse it.
Branches
- Feature/fix/refactor work branches off the integration branch, never
main
(unless main IS the integration branch).
- Exception:
hotfix/ may branch off main for urgent production fixes.
- Naming:
type/scope-short-description, lowercase kebab-case.
- Valid types:
feat, fix, chore, docs, refactor, test, hotfix.
- Examples:
feat/serial-connection, fix/hex-view-overflow, chore/update-deps.
Commits
- Atomic: one logical change per commit. If the description needs "and", split it.
- Format:
type(scope): subject
type: feat, fix, chore, docs, refactor, test, perf, ci, build, style.scope (optional): affected area (serial, ui, docs...).subject: imperative mood, lowercase first word, no trailing period, ≤72 chars.
- Body: explain why, not what. Wrap at ~72 chars. Reference issues/ADRs.
- Breaking change:
feat(api)!: ... plus a BREAKING CHANGE: <reason> footer.
- Stage only the files relevant to the commit. Never bundle unrelated changes.
- Never push unless the user explicitly asks.
Procedure
- Confirm you are on a correctly named branch off the integration branch.
- Stage the files for one logical change.
- Re-read the staged diff.
- Write the commit message following the format above.
- Repeat per logical change until the work is fully committed.
- Never push unless the user explicitly asks.
Examples
feat(serial): add port discovery with USB metadata
fix(ui): prevent terminal overflow on rapid input
docs(adr): add DT-0001 tech stack selection
refactor(ipc)!: replace command interface
BREAKING CHANGE: clients must use new invoke() signatures.
1---2name: conventional-commit3description: Use when creating git commits or branches. Enforces Conventional Commits formatting, atomic English commits, and branch naming (type/scope-description) off the integration branch. Triggers on commit, branch, git, Conventional Commits, PR.4---56# Conventional Commit & Branch Workflow78Enforce the repository's git conventions. All commit and branch text is **English**.9The integration branch defaults to `dev`; if the repo uses another name10(`main`, `develop`), ask once and reuse it.1112## Branches1314- Feature/fix/refactor work branches off the **integration branch**, never `main`15 (unless `main` IS the integration branch).16 - Exception: `hotfix/` may branch off `main` for urgent production fixes.17- Naming: `type/scope-short-description`, lowercase `kebab-case`.18- Valid types: `feat`, `fix`, `chore`, `docs`, `refactor`, `test`, `hotfix`.19- Examples: `feat/serial-connection`, `fix/hex-view-overflow`, `chore/update-deps`.2021## Commits2223- **Atomic**: one logical change per commit. If the description needs "and", split it.24- Format: `type(scope): subject`25 - `type`: `feat`, `fix`, `chore`, `docs`, `refactor`, `test`, `perf`, `ci`, `build`, `style`.26 - `scope` (optional): affected area (`serial`, `ui`, `docs`...).27 - `subject`: imperative mood, lowercase first word, no trailing period, ≤72 chars.28- Body: explain **why**, not what. Wrap at ~72 chars. Reference issues/ADRs.29- Breaking change: `feat(api)!: ...` plus a `BREAKING CHANGE: <reason>` footer.30- Stage only the files relevant to the commit. Never bundle unrelated changes.31- Never push unless the user explicitly asks.3233## Procedure34351. Confirm you are on a correctly named branch off the integration branch.362. Stage the files for **one** logical change.373. Re-read the staged diff.384. Write the commit message following the format above.395. Repeat per logical change until the work is fully committed.406. Never push unless the user explicitly asks.4142## Examples4344```45feat(serial): add port discovery with USB metadata46fix(ui): prevent terminal overflow on rapid input47docs(adr): add DT-0001 tech stack selection48refactor(ipc)!: replace command interface4950BREAKING CHANGE: clients must use new invoke() signatures.51```
eminboydak