mirror of
https://github.com/Sea-Haven-Industries/engineering-handbook.git
synced 2026-09-30 08:03:16 +00:00
73 lines
2.5 KiB
Markdown
73 lines
2.5 KiB
Markdown
|
# Issue Tracking
|
||
|
|
|
||
|
|
All work is tracked in Jira. Jira is the source of truth for work; GitHub is the source of truth for code. Link them rather than duplicating issues.
|
||
|
|
|
||
|
|
## Projects
|
||
|
|
|
||
|
|
| Key | Project | Use for |
|
||
|
|
|---|---|---|
|
||
|
|
| `DEV` | Software Development | Product features, application bugs, customer-facing work |
|
||
|
|
| `PLAT` | Infrastructure and Platform | AWS, networking, CI/CD, internal tooling |
|
||
|
|
| `SEC` | Security | Security findings, remediations, audits, access reviews |
|
||
|
|
|
||
|
|
Board columns are **To Do / In Progress / Blocked / Done**.
|
||
|
|
|
||
|
|
## Linking to GitHub
|
||
|
|
|
||
|
|
GitHub is connected to Jira. When the Jira key appears at the end of the PR title, for example `feat(parser): add receipt parser (DEV-123)`, the branch, commits, and PR show up on the Jira issue automatically.
|
||
|
|
|
||
|
|
## Ticket template
|
||
|
|
|
||
|
|
Every ticket description has these four sections. If a section has nothing in it, say so; do not delete it.
|
||
|
|
|
||
|
|
```markdown
|
||
|
|
## Context
|
||
|
|
|
||
|
|
## Scope
|
||
|
|
|
||
|
|
## Business rules
|
||
|
|
|
||
|
|
## Acceptance Criteria
|
||
|
|
```
|
||
|
|
|
||
|
|
### Context
|
||
|
|
|
||
|
|
Why the work exists. Name the affected systems specifically (repo, service, function name) and link related tickets and PRs.
|
||
|
|
|
||
|
|
| Good | Bad |
|
||
|
|
|---|---|
|
||
|
|
| The `payments-processor` Lambda times out on files over 10 MB. Found while working DEV-123. | The importer is slow sometimes. |
|
||
|
|
|
||
|
|
### Scope
|
||
|
|
|
||
|
|
What is in scope, and explicitly what is not. Link the ticket that owns anything out of scope.
|
||
|
|
|
||
|
|
| Good | Bad |
|
||
|
|
|---|---|
|
||
|
|
| In scope: raise the timeout and add a size guard. Out of scope: streaming parser rewrite (DEV-124). | Fix the importer. |
|
||
|
|
|
||
|
|
### Business rules
|
||
|
|
|
||
|
|
Constraints that must hold during and after the work: data that must not be lost, behavior that must not regress, limits that must not be exceeded.
|
||
|
|
|
||
|
|
| Good | Bad |
|
||
|
|
|---|---|
|
||
|
|
| In-flight uploads must not be dropped during the deploy. Existing records keep their IDs. | Don't break anything. |
|
||
|
|
|
||
|
|
### Acceptance Criteria
|
||
|
|
|
||
|
|
A checklist of items that can each be verified on its own. Prefer a command or observable result over a claim.
|
||
|
|
|
||
|
|
```markdown
|
||
|
|
## Acceptance Criteria
|
||
|
|
- [ ] A 25 MB upload completes without a timeout error in the logs
|
||
|
|
- [ ] Uploads over 50 MB return 413 with a descriptive message
|
||
|
|
- [ ] The README documents the new size limit
|
||
|
|
```
|
||
|
|
|
||
|
|
## Ticket hygiene
|
||
|
|
|
||
|
|
- **Close with evidence.** When closing, comment with what resolved it: the merged PR or the ticket that took over the remaining work.
|
||
|
|
- **Fix stale descriptions first.** Before starting an old ticket, check it against the current state and rewrite anything that no longer holds.
|
||
|
|
- **Keep epics honest.** Close an epic once its children are done, or add tickets for the work that remains.
|