Bug Report

Oh No! You found a bug! Let's get it fixed by following the following process.

Bugs are the highest priority Tickets. Bug reports go into the top of "ready to-do" column on the Kanban and use the default issue template.

For developers:

If a bug needs further clarification, keep it at the top of the "ready to-do" column, but ask questions and move on the next ticket.

If you can't reproduce the bug shift it into "Done Staging" column.

When you come back for your next ticket, check the bug until clarified.

Information and Templates

Template Report

Bug triage

Bugs have the highest priority and go straight into the top of "ready" and follow the following process:

If a bug needs further clarification, keep it at the top of "ready", but ask questions and move on the next ticket. When you come back for your next ticket, check the bug until clarified.

Root cause analysis

When catching a bug cast a wide net. Could better software design have prevented the bug? If so, create an additional tech-debt ticket that describes the improved design and place it at the top of "clarify".


Follow the 'campfire rule' -- don't just fix the bug. Leave the code in a better state than when you found it. Refactoring for clarity and improving test and type checking coverage

Expected Behavior

Please describe the behavior you are expecting

Current Behavior

What is the current behavior?

Failure Information (for bugs)

Please help provide information about the failure if this is a bug. If it is not a bug, please remove the rest of this template.

Steps to Reproduce

Please provide detailed steps for reproducing the issue.

  1. step 1

  2. step 2

  3. you get it...


Please provide any relevant information about your setup. This is important in case the issue is not reproducible except for under certain conditions.

Failure Logs

Please include any relevant log snippets or files here.

Steps to Resolve Bug Report

This section documents the process of how our development team resolves bug reports.

Step 0 - Clarification

Despite being in "ready" a bug may need clarification. If so, keep the ticket at the top of "ready", but ask questions and move on the next ticket.

When you come back for your next ticket, check the bug ticket until clarified.

Step 1 - Reproduce

Visit staging and attempt to reproduce the bug. If you can't reproduce the bug shift staging into "staging" and tag the orignal bug finder If you can reproduce the bug proceed to to step 2.

Step 2 - Root cause analysis.

Assign yourself to the ticket and shift to "in-progress".

Why did the bug occur? Cast a wide net and think about. Does the bug point to larger issue? Perhaps the data structures are forcing developers to write workarounds.If so, make technical debt ticket. Proceed to step 3.

Step 3 - Triage

Most bugs will fall into one or more of the following categories:

  • "critical path"

  • "database / API"

  • "unit logic"

  • "interaction" / "styling"

  • "type error"

Critical path

A critical path bug compromisese the core functionality of the app. For example we encountered a bug on the assessment submission form where the user was not redirected the submitted page. These bugs correspond to acceptance tests - cypress/integration/**

Database / API

Its possible that a database function or API call has incorrect logic or does not account for a particular case. The bugs correspond to integration or database unit tests - __tests__/intgration/** or db/test**.

Unit logic

The bug may stem from incorrect logic or unhandled cases in an isolated function call. These bugs correspond to unit tests - __tests__/unit/**

Interaction / Styling

Type errors

if the bug cuts across several categories (for example, UI and critical path) it may need to be broken up into several tickets.

Step 4 - Tests

From the previous step we now understand the nature of the bug and the kind of tests we need

Commit your code and push to a branch bug/<BUG NAME>.

Step 5 - "Inside out" development.

If you have multiple tests proceed from the smallest piece first, (eg. unit)

Step 6 - Improvement

Step 7a - Merge with mainline development

Once all tests pass and the code has been improved and type checked you may:

  1. squash all commits and push to your bug branch.

  2. open a pull request from the bug branch into dev.

At this point the CI will run all integration and unit tests. If CI tests pass you may merge your pull request into dev and proceed to Step 8. If CI tests fail proceed to Step 7b.

Step 7b - Fix and review.

Inspect the test logs in the CI and triage the error. If the error is obvious fix and proceed to step 7a. If the error is mysterious @mention another developer.

Step 8 - Quality Analysis

Visit the freshly deployed app on the dev server and attempt to reproduce the bug. If you cannot reproduce the bug and proceed to step 9. @mention the original bug finder asking them confirm the bug has been resolved.

Step 9 - To staging and beyond!

Pull the latest dev and merge into master locally on your own machine. Conduct Step 4 - Tests.