# JIRA Engineering Guide ### How teams manage work, sprints, and delivery in Jira This guide defines how engineering teams use Jira to plan, track, and deliver work. The goal is not process for the sake of process. The goal is to ensure: * Work is visible * Teams stay focused * Blockers surface quickly * Engineering metrics remain accurate Jira should reflect **how work actually happens**, not create unnecessary bureaucracy. *** ## 1. Jira Project Setup ### Use Company-Managed Projects All engineering projects should use **Company-Managed Projects**. Benefits: * shared workflows * consistent metrics * easier administration * cross-team reporting *** ### Use a Master Project Template Create one project as the base template: ``` TEMPLATE: Standard Software Project ``` When creating new projects: 1. Select **Company-Managed** 2. Choose **Create with shared configuration** 3. Copy configuration from the template This ensures all teams start with the same: * workflows * issue types * fields * board configuration *** ### Avoid Too Many Projects Projects should represent **products or services**, not teams. Bad example: ``` Frontend Team Backend Team Infra Team ``` Better structure: ``` Payments Platform Analytics Mobile ``` Use **Components** inside projects to represent system areas. *** ## 2. Issue Types & Work Hierarchy Use consistent issue types across projects. | Issue Type | Purpose | | ---------- | ---------------------------------------------------- | | Epic | Large initiative spanning multiple sprints | | Story | User-facing feature or requirement | | Task | Technical work not tied to a user story | | Bug | Defect discovered during development or testing | | Incident | Production issue affecting customers | | Sub-task | Small step within a story shared across contributors | *** ### When to Use Epics If work cannot be completed within one sprint, it likely belongs in an **Epic**. Example: Epic ``` Launch Payment Retry System ``` Stories ``` Retry payment API Retry UI flow Payment retry logging ``` *** ## 3. Components vs Labels Both help categorize work but serve different purposes. ### Components Used for **stable system areas** Example: ``` Frontend Backend Infrastructure API Mobile ``` Limit components to **5–7 major areas**. *** ### Labels Used for **temporary tags or themes** Example: ``` tech-debt security migration experiment performance ``` Avoid using labels for system areas. *** ## 4. Workflow Design Workflows should remain **simple and consistent**. Recommended workflow: ``` Backlog → To Do → In Progress → In Testing → Ready For Release → Done ``` Why simplicity matters: Teams often forget to update complex workflows, which breaks delivery metrics like cycle time. If additional QA steps exist, they can happen within **Review**. *** ### Jira Status Categories Jira groups statuses into three categories: | Category | Meaning | | -------- | ----------- | | Blue | To Do | | Yellow | In Progress | | Green | Done | Ensure statuses map correctly. Example: ``` In Testing → In Progress category Ready For Release → In Progress category ``` Otherwise, Jira may treat work as completed too early. *** ## 5. Handling Blockers Avoid creating a separate **Blocked status** in most cases. Instead use **Jira Flags**. How to flag: ``` Right click issue → Add Flag ``` Example scenario: ``` Waiting for API documentation Waiting for design approval ``` Ticket remains: ``` In Progress (Flagged) ``` Create a **Blocked status only if your organization needs blocked-time metrics**. *** ## 6. Board Setup & Work-in-Progress Limits Boards should mirror the workflow: ``` Backlog To Do In Progress In Review Done ``` *** ### WIP Limits Avoid starting too many tasks simultaneously. Recommended rule: ``` WIP Limit = Team Size × 1.5 ``` Example: 3 developers → WIP limit of 4–5. This encourages finishing work before starting new work. *** ## 7. Git Integration & Pull Request Linking All code changes must link to Jira issues. Recommended branch naming: ``` PROJ-123-add-payment-retry ``` Commit message example: ``` [PROJ-123] Implement retry logic ``` Benefits: * automatic linking between code and tickets * automated workflow updates * accurate delivery metrics *** ## 8. Ticket Fields & Data Quality Keep ticket forms simple. Required fields: ``` Summary Description Priority Developer Assignee Sprint Epic Link Story Points Labels ``` Too many fields lead to poor data quality. *** ### Story Description Format Recommended template: ``` As a [user role] I want [action] So that [value] ``` Example: ``` As a merchant I want failed payments retried automatically So that customers can complete checkout successfully ``` *** ## 9. Definition of Ready Stories must meet these criteria before entering a sprint: * description completed * acceptance criteria defined * dependencies identified * story points estimated * epic linked Stories that do not meet these criteria should remain in the backlog. *** ## 10. Definition of Done A ticket can move to **Done only when:** * Code is merged to main branch * PR review completed * Automated tests pass * QA validation completed (if applicable) * Documentation updated if required Example failure case: ``` PR merged → ticket marked Done → deployment happens days later ``` This breaks deployment metrics. *** ## 11. Estimation Best Practices Use the Fibonacci scale: ``` 1, 2, 3, 5, 8, 13 ``` Guidelines: Stories larger than **13 points should usually be split**. Exception: if the work is well understood but large. *** ### Bug Estimation Estimate bugs only when they require significant effort. Do not estimate: ``` Fix UI typo ``` Estimate: ``` Investigate memory leak in payment service ``` *** ## 12. Backlog Hygiene Backlogs should remain manageable. ### Limit backlog size Backlog should contain **2–3 sprints worth of ready work**. *** ### Remove stale tickets Tickets older than **90 days** should be: ``` Closed as Won't Do or moved to Ideas backlog ``` *** ### Avoid vague tickets Bad: ``` Improve performance ``` Better: ``` Reduce billing API query latency from 600ms to 200ms ``` *** ## 13. Sprint Lifecycle Every sprint follows four phases. *** ## Phase 1 - Backlog Refinement Ensure stories meet the **Definition of Ready**. Product owner prioritizes backlog. Highest value items appear at the top. *** ## Phase 2 - Sprint Planning During planning: 1. review sprint goal 2. estimate capacity 3. select work 4. assign ownership *** ### Capacity Planning Account for non-development time: ``` meetings on-call rotations support tasks holidays ``` Recommended planning capacity: ``` 70–80% of theoretical velocity ``` Example: Team velocity = 40 Sprint commitment = \~30 points. *** ### Sprint Goal Discipline Each sprint should have **one clear goal**. Example: Good: ``` Enable credit card payments in checkout ``` Bad: ``` Work on multiple improvements ``` When new work appears mid-sprint, ask: > Does it support the sprint goal? *** ## Phase 3 - During the Sprint Daily standups should focus on: * blockers * risks to the sprint goal * coordination Bad standup: ``` Yesterday I coded Today I will code ``` Better standup: ``` What is blocking progress? What threatens the sprint goal? ``` *** ### Pull Request Review Discipline One of the most common delays in teams is slow code reviews. Rule: ``` PR review SLA: 24 hours ``` Developers should check the **Review column first** before starting new work. *** ## Phase 4 - Closing the Sprint At the end of the sprint: 1. move unfinished work back to backlog 2. re-evaluate estimates 3. start next sprint Always click: ``` Complete Sprint ``` Leaving sprints open causes reporting errors. *** ## 14. Incident Handling Production incidents interrupt normal sprint work. Incident tickets should: * bypass sprint planning * be prioritized immediately * be resolved regardless of the sprint scope After resolution, conduct a **post-incident review**. *** ## 15. Common Real-World Scenarios ### Scope Changes During Development If requirements change significantly: ``` Close ticket as Discarded Create a new ticket ``` This prevents inflated cycle time metrics. *** ### Waiting on Design If design is missing: * flag ticket * tag designer If the delay exceeds 48 hours, consider moving the ticket back to backlog. *** ### External Dependencies Example: ``` Waiting on vendor API Waiting on legal approval ``` Flag the ticket and document the dependency. *** ### Oversized Story Discovered Midway If a story grows larger than estimated: ``` Split it into smaller tickets ``` Large hidden work destabilizes sprint planning. *** ## 16. Operational Discipline Rules ### Ticket Ownership Teams use a **Developer field** to identify the primary contributor responsible for implementation. Guidelines: * **Assignee** represents the person currently responsible for the ticket. * **Developer field** represents the engineer implementing the work. *** ### Story Points Estimate: ``` Stories Tasks Large Bugs ``` Do not estimate: ``` Sub-tasks ``` *** ### Ticket Movement Rule If a ticket has not moved for **2 days**, raise it in standup. It may be blocked. *** ### Shadow Work Policy If work is not in Jira, it did not happen. Integrate Jira with Git so: * branches * commits * PRs automatically link to tickets. *** ## Final Principle The purpose of this guide is not process - it is **clarity and delivery reliability**. When teams follow these practices: * work becomes visible * blockers surface quickly * planning improves * engineering metrics remain accurate Jira then becomes a reliable system for understanding **how engineering teams deliver software**. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://typo.gitbook.io/typo-help-docs/faqs/jira-engineering-guide.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.