adam/engineering-handbook
1
0
Fork 0
mirror of https://github.com/Sea-Haven-Industries/engineering-handbook.git synced 2026-09-30 15:03:14 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

Add Jira issue-linking convention

Browse source 
Work is tracked in Jira while code lives in GitHub; the org-level GitHub
for Jira app is already installed but nothing told contributors how to
trigger the link. Document putting the Jira key in the branch name, PR
title, or Refs trailer so branches, commits, and PRs thread into the
issue's development panel. Use a generic PROJ-123 placeholder rather
than naming specific projects, which change over time.
This commit is contained in:
Adam Moussa 2026-06-02 19:36:03 -04:00
parent 7d5d04985a
commit e749e6f651
2 changed files with 40 additions and 5 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

13
commit-messages.md
View file

@ -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
```

32
git-workflow.md
View file

@ -8,18 +8,44 @@
| Prefix | Use when |
|---|---|
| `feature/<description>` | Adding new functionality or enhancing existing features |
| `bug/<description>` | Fixing a non-urgent defect found during development or testing |
| `hotfix/<description>` | Fixing a production issue that needs immediate attention |
| `feature/<key>-<description>` | Adding new functionality or enhancing existing features |
| `bug/<key>-<description>` | Fixing a non-urgent defect found during development or testing |
| `hotfix/<key>-<description>` | 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 <text>` | Add a comment to the issue |
| `PROJ-123 #time 2h <text>` | 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: