Emma Thorpe
1d5a5adbcc
The previous commit required a ticket scope on every commit in every repository. This repository has no Jira project, so the rule as written would either block a commit or invite a fabricated WSP number. Record the exception: in personal repositories the scope is the area of the change (claude, deps, hosts) and conventional form still applies. The ticket requirement is scoped to the Jira-backed work repositories that enforce it in CI.
4.5 KiB
name, description, metadata
| name | description | metadata | ||||||
|---|---|---|---|---|---|---|---|---|
| git-conventions | Branch naming and commit message conventions for git workflow |
|
Never commit directly to the default branch (main/master). Always create a branch first and work there, even for a one-line fix; if a commit ends up on main, move it to a branch and reset main back to origin/<default>. This is a hard rule.
Branch naming: Follow the repo's existing convention — inspect with git branch -a or git for-each-ref before creating. Prefer Conventional Commits prefixes (feat/, fix/, chore/, docs/, refactor/). Format: <prefix>/<TICKET-ID>-<kebab-summary>. Only ask if no convention is discoverable.
Commit messages — every commit, without exception: <type>(<TICKET-ID>): <imperative summary>. The ticket ID goes in the scope. Use additional -m flags for rationale/body. Commit at logical checkpoints, not one giant final commit.
<TICKET-ID> is the real ticket for the work in hand. It is a symbol to substitute, never a literal — if a commit subject ever reaches git still containing <TICKET-ID>, or a made-up number, that is a defect. Establish the actual ID before the first commit, in this order:
- The ticket Lyra named in the request.
- The current branch name —
task/WSP-32542/remove-wspgov-terraformgivesWSP-32542. Extract it:git branch --show-current | grep -oE '[A-Z]{2,}-[0-9]+'. - The ticket the branch's existing commits already use.
If none of those yield an ID, ask which ticket to file the work under. Do not guess, do not reuse the ID from an unrelated earlier task in the session, and do not invent a plausible-looking number. Every commit in a branch normally carries the same ID; if the work genuinely spans two tickets, split the commits accordingly rather than picking one at random.
Exception — repos with no issue tracker. Personal repos such as nixfiles have no Jira project. There the scope is the area of the change, not a ticket: chore(claude): ..., chore(deps): ..., feat(hosts): .... Conventional form is still required; only the ticket scope is dropped. Never invent a WSP number to satisfy the rule in a repo that has no tickets. The ticket requirement applies to the work repos under ~/code that are backed by the WSP Jira project and gated by CI.
This format is mandatory and overrides the repo's existing log style. Many repos (multicluster, core-services-cloud) have histories full of bare <TICKET-ID>: summary subjects written by other people. Do not copy that. Match repo style for branch names only; commit subjects are always full Conventional Commits with the ticket scope. CI enforces this, and a failure means Lyra rebases the history by hand.
Known failure mode — scope decay across a session. The first commit gets fix(<TICKET-ID>): ... correctly, then follow-up commits in the same sitting degrade to bare test: add tests for class, refactor: hoist middleware, chore: tidy. This has caused real rebase work in core-services-cloud. The second, third and fifth commits need the ticket scope exactly as much as the first. Re-read the subject against the format before every single git commit.
Merge commits count too. Prefer git rebase origin/<base> over git merge so none is created. If unavoidable, set the message explicitly: git merge --no-ff -m "<TICKET-ID>: merge master into <branch>". Keep the ID uppercase; the check is case-sensitive.
Before pushing, verify — do not skip this:
git log --format=%s origin/<base>..HEAD | grep -vE '^[a-z]+(\([A-Z]{2,}-[0-9]+\))!?: '
Must print nothing. Writing each subject carefully is not a substitute for running it.
Auditing past behaviour is unreliable. If Lyra has already rebased to fix a bad subject, the log shows her corrected version, not what was originally written. A clean git log is not evidence that nothing was wrong. Check author date vs committer date (--format="%ad %cd") — a mismatch means history was rewritten. Never argue from a clean log that the fault did not occur.
Why: Lyra's standard workflow for traceability, and a hard CI gate. A malformed subject is manual rebase work for her, not just a red build.
How to apply: Conventional form on every commit in every repo; the ticket scope additionally on every commit in a Jira-backed work repo. Format first, repo style second. Run the verification grep before every push. Relates to git_check_state.