diff --git a/commit-messages.md b/commit-messages.md index 2541b0e..569660d 100644 --- a/commit-messages.md +++ b/commit-messages.md @@ -66,9 +66,18 @@ Optional body wrapped at 72 characters. Explain the problem this commit solves and why this approach was chosen. Mention side effects or non-obvious consequences. -Refs: #123 +Refs: PROJ-123, #123 ``` +## Referencing issues + +Use the `Refs:` trailer to point at the work this commit relates to: + +- **Jira key** (`PROJ-123`) when the work tracks a Jira issue. The GitHub for Jira app reads the key and threads the commit into the issue's development panel. See [git-workflow.md](git-workflow.md#linking-to-jira). +- **GitHub issue** (`#123`) when the work tracks a GitHub issue in the same repo. + +List both when both apply: `Refs: PROJ-123, #123`. The key only needs to appear once in the branch, PR title, or any commit for the link to form, but including it in the trailer keeps the reference attached to the individual change. + ## Example ``` @@ -79,5 +88,5 @@ deployments. Without retries, these surface as user-facing errors. This adds exponential backoff with 3 attempts, which matches the upstream's documented recovery window. -Refs: #45 +Refs: PROJ-123 ``` diff --git a/git-workflow.md b/git-workflow.md index 236c62d..4965480 100644 --- a/git-workflow.md +++ b/git-workflow.md @@ -8,18 +8,44 @@ | Prefix | Use when | |---|---| -| `feature/` | Adding new functionality or enhancing existing features | -| `bug/` | Fixing a non-urgent defect found during development or testing | -| `hotfix/` | Fixing a production issue that needs immediate attention | +| `feature/-` | Adding new functionality or enhancing existing features | +| `bug/-` | Fixing a non-urgent defect found during development or testing | +| `hotfix/-` | Fixing a production issue that needs immediate attention | **bug vs hotfix:** Use `bug/` for defects caught before they affect production (failing tests, broken dev flows, issues found in review). Use `hotfix/` only when production is impacted and the fix needs to bypass normal review cadence. +**Jira key:** When the work tracks a Jira issue, put the key after the prefix: `feature/PROJ-123-add-receipt-parser` (substitute the real project key, e.g. the infra or software-development project). This is what wires the branch, commits, and PR into the issue's development panel. See [Linking to Jira](#linking-to-jira) below. Work with no Jira issue (one-off scripts, trivial fixes) omits the key and uses a plain description. + ## Commits - Commit each logical change individually with a descriptive message - See [commit-messages.md](commit-messages.md) for formatting rules - Keep the working tree clean: commit or stash before switching context +## Linking to Jira + +Work is tracked in Jira (`seahaven.atlassian.net`). Jira is the source of truth for *work*; GitHub is the source of truth for *code*. We do not duplicate issues between the two — we link them. + +The org-level **GitHub for Jira** app is already installed across all repos. It detects the Jira issue key (e.g. `PROJ-123`) wherever it appears and surfaces the branch, commits, PR, and deployment status in that issue's development panel automatically. To make that happen, mention the key in at least one of: + +- the branch name (`feature/PROJ-123-add-receipt-parser`) +- the PR title (`[PROJ-123] Add receipt parser`) +- a commit message (the `Refs:` trailer, see [commit-messages.md](commit-messages.md)) + +Mentioning it in the branch name covers all three at once, so that is the minimum bar. + +### Smart Commit commands + +The integration also accepts inline commands in commit messages to act on the issue without opening Jira: + +| Command | Effect | +|---|---| +| `PROJ-123 #comment ` | Add a comment to the issue | +| `PROJ-123 #time 2h ` | Log work | +| `PROJ-123 #done` (or another transition name) | Transition the issue | + +Transition names are case-insensitive and match the issue's workflow (`#in-progress`, `#done`). Use these sparingly; the link itself is the main goal, not driving the whole workflow from commits. + ## Deploy-Then-Merge The standard flow for changes that deploy to AWS: