Emma Thorpe
4029866ed4
The git conventions memory said to match the repository's existing log style. Several repositories (multicluster, core-services-cloud) have histories dominated by bare "WSP-1234: summary" subjects, so matching them produced commits that were not in conventional form. A related failure was scope decay within a session: the first commit was correct and later ones degraded to bare "test:" or "refactor:" subjects. Both required commit history to be rebased by hand. - Make "<type>(<TICKET-ID>): <summary>" mandatory on every commit and explicitly override repository log style. Style matching now applies to branch names only. - Describe how to establish the real ticket ID (named in the request, extracted from the branch, or taken from existing commits on the branch) and require asking rather than guessing when none is available. Replace the literal WSP-1234 examples with <TICKET-ID> so the placeholder cannot be committed verbatim. - Record scope decay across a session as a named failure mode. - Cover merge commits, preferring rebase and requiring an explicit message when a merge commit is unavoidable. - Add a pre-push verification grep that must return no output. - Note that a clean git log does not prove a subject was correct when written, because rebasing replaces it; compare author and committer dates instead. Update the MEMORY.md index entry to match.
41 lines
3.9 KiB
Markdown
41 lines
3.9 KiB
Markdown
---
|
|
name: git-conventions
|
|
description: Branch naming and commit message conventions for git workflow
|
|
metadata:
|
|
node_type: memory
|
|
type: feedback
|
|
originSessionId: ca09fbe4-9226-4ad9-874f-04df90840eef
|
|
---
|
|
|
|
**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:
|
|
|
|
1. The ticket Lyra named in the request.
|
|
2. The current branch name — `task/WSP-32542/remove-wspgov-terraform` gives `WSP-32542`. Extract it: `git branch --show-current | grep -oE '[A-Z]{2,}-[0-9]+'`.
|
|
3. 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.
|
|
|
|
**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:** On every commit in every repo. Format first, repo style second. Run the verification grep before every push. Relates to [[git_check_state]].
|