JIRA Setup 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:
When creating new projects:
Select Company-Managed
Choose Create with shared configuration
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:
Better structure:
Use Components inside projects to represent system areas.
2. Issue Types & Work Hierarchy
Use consistent issue types across projects.
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
Stories
3. Components vs Labels
Both help categorize work but serve different purposes.
Components
Used for stable system areas
Example:
Limit components to 5–7 major areas.
Labels
Used for temporary tags or themes
Example:
Avoid using labels for system areas.
4. Workflow Design
Workflows should remain simple and consistent.
Recommended workflow:
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:
Blue
To Do
Yellow
In Progress
Green
Done
Ensure statuses map correctly.
Example:
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:
Example scenario:
Ticket remains:
Create a Blocked status only if your organization needs blocked-time metrics.
6. Board Setup & Work-in-Progress Limits
Boards should mirror the workflow:
WIP Limits
Avoid starting too many tasks simultaneously.
Recommended rule:
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:
Commit message example:
Benefits:
automatic linking between code and tickets
automated workflow updates
accurate delivery metrics
8. Ticket Fields & Data Quality
Keep ticket forms simple.
Required fields:
Too many fields lead to poor data quality.
Story Description Format
Recommended template:
Example:
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:
This breaks deployment metrics.
11. Estimation Best Practices
Use the Fibonacci scale:
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:
Estimate:
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:
Avoid vague tickets
Bad:
Better:
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:
review sprint goal
estimate capacity
select work
assign ownership
Capacity Planning
Account for non-development time:
Recommended planning capacity:
Example:
Team velocity = 40
Sprint commitment = ~30 points.
Sprint Goal Discipline
Each sprint should have one clear goal.
Example:
Good:
Bad:
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:
Better standup:
Pull Request Review Discipline
One of the most common delays in teams is slow code reviews.
Rule:
Developers should check the Review column first before starting new work.
Phase 4 - Closing the Sprint
At the end of the sprint:
move unfinished work back to backlog
re-evaluate estimates
start next sprint
Always click:
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:
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:
Flag the ticket and document the dependency.
Oversized Story Discovered Midway
If a story grows larger than estimated:
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:
Do not estimate:
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.
Last updated