Using JIRA
- Titus Chow
JIRA is an issue tracker, used to keep track of ongoing projects and provide context to changes that we've made. In Electrical, we use a relatively simple JIRA workflow.
Issues
There are 3 main types of issues:
- Story: Describes an issue or task, focusing on its responsibilities, outcome, or impact.
- Bug: Describes something that needs to be fixed.
- Epic: Essentially categories or milestones, encompassing a set of stories or bugs.
We generally use epics to organize other issues by their systems. When creating a story or bug, you'll see a number of fields.
| Field | Content | Purpose |
|---|---|---|
| Summary | [System] Very brief summary | The system (usually the shortname of the corresponding epic) is tagged to make it easier to distinguish issues across systems. The summary should be extremely brief, probably around 4 to 10 words at most. It should describe the issue at a high-level, focusing on the impact rather than implementation. |
| Reporter | User picker - set to you by default | It's important to know who made the issue so we can request for clarification if necessary. Do not change this field. |
| Description | Detailed description of the issue, possible causes/fixes/implementations | This should be a relatively detailed description, including the purpose, possible implementations, links to documentation, and other important information. |
| Priority | Usually medium | This should reflect the urgency of the issue. Higher priority issues are blocking or have hard deadlines. Most issues are medium-level, which is the normal priority. |
| Assignee | User picker - either you or unassigned | This is the person who should be responsible for addressing the issue. If you're creating this issue for yourself, assign it to yourself. Otherwise, unless you're an electrical lead, leave it unassigned and let the system owner know. |
| Epic Link | Corresponding epic | This should be set to the epic that corresponds to the system you're working on. |
| Sprint | Pick the currently active electrical sprint or leave it blank | This is just used to keep track of how issues are progressing. If this issue is something that should be done within the next few weeks, pick the currently active electrical sprint. Otherwise, if it's something that's more of a reminder of something that needs to be done eventually, leave it blank. |
| Original Estimate | Approximate estimate of the number of days it'll take | This should be an estimate of time it'll realistically take to complete the issue. This should account for testing and reviews. We don't expect it to be extremely accurate, but it should at least reflect the workload required. |
| Team Members | Multi-user picker - leave it blank | This is just a multi-user picker if you want to track some additional people. Note that using this field will not inform those people that they have been added to this issue and is purely cosmetic. |
If a field wasn't mentioned, leave it blank.
Workflow
A great view for looking at current issues is the Backlog. You can see the ongoing issues being handled in the current sprint and issues we have yet to address in the backlog.
The general workflow for an issue goes like this: Open → In Progress → Closed. Once an issue has been made and assigned, the assignee (usually you) is responsible for updating the issue's progress. This can be done on the issue's page by clicking the corresponding button.
The default state of an issue is Open. This means that the assignee has not yet begun work on the issue. If there is no assignee, feel free to assign the issue to yourself. Once work has begun on the issue, it should be transitioned to the In Progress state. Finally, once the work has been reviewed, approved, and merged, the issue can be Closed. When closing an issue, please specify the resolution and a short description of what was changed or the reason for closing the issue.
If an issue starts to grow in scope, we recommend creating more issues to address the new changes instead of integrating them into the current issue. This results in more focused issues and keeps reviews short. Too many changes in a single review will likely result in missed bugs.
Git Integration
We use Git for version control, where master is the stable branch and all development is done in feature branches. For more information, see our Git Workflow page.
By mentioning issue numbers in commits and PRs, JIRA can track development activity and link it to the corresponding issue. This also gives context to our commits, allowing us to find the issue and read the detailed description for some background.