mirror of
https://github.com/Sea-Haven-Industries/engineering-handbook.git
synced 2026-10-02 10:53:16 +00:00
735b407017
Partner engineering teams need the standards without access to this repo, which contains internal repo names, account identifiers, and migration history. Adds eight simplified pages, one per Confluence page, plus an internal README with source mapping and exclusions. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01UP6j3hYgoVqjKZwC3XB9ay
72 lines
2.5 KiB
Markdown
72 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.
|