Reporting a bug
A bug report exists so that a developer who was not there can make the problem happen on their own machine. Everything in the report serves that.
There are two ways to file, and they point at each other:
- In the app — press Fail on the step, or open avatar menu → Report a test step (keyboard: Alt+Shift+R). The form is pre-filled with the page, the client, the build, your browser and screen size; you add the steps, expected and actual, and a screenshot (you can paste one straight into the form). It becomes a GitHub issue.
- In the workbook — one row on the Defects tab. This is where severity, priority, triage status and retest live.
Do both for every Fail: the app for the developers, the workbook for the lead. Paste the GitHub issue link into the workbook row so the two records are joined.
The Defects tab, field by field​
| Field | How to fill it |
|---|---|
| Defect ID | Next number in sequence: DEF-002, DEF-003. Copy it into the Defect ID column of every step it explains. |
| Round | R1. |
| Title | One line, specific. "Password-reset link returns 404 on Android" is good. "Login broken" is not. |
| Step ID, Module | Where you found it. If several steps fail from it, put the first one here and list the rest in Notes. |
| Severity | Blocker, Major, Minor or Cosmetic, from the definitions in Terms. Judge from the user's point of view, and when in doubt go one level higher; the lead can lower it at triage. |
| Priority | Leave blank. The lead sets it at triage. |
| Status | New. It moves to Triaged, In Progress, Fixed – Pending Verify, then Verified, or to Won't Fix, Duplicate or Not a Bug. |
| Surface, Environment / Build | Where it happened and the exact build ID from the Environments tab. Not optional. |
| Reported By, Assigned To | You, and blank (the lead assigns a developer). |
| Steps to Reproduce | Numbered, from a known starting point, one action per line. Include the account you used and the data you typed. Anyone should be able to follow them without asking you a question. |
| Expected, Actual | What the checklist said should happen, and what did. Quote error messages exactly. |
| Evidence Link | Screenshot or recording. On the phone, a screen recording of the whole attempt is often the most useful evidence there is. |
| GitHub Issue | The issue link from the app's Fail button or report form. |
| Fixed In Build, Verified By, Verified On | Filled at retest. |
A weak report and a strong one​
Weak
Title: Export not working Steps: tried to export, got an error Expected: export works Actual: error
A developer cannot act on this without three follow-up messages: which project, which format, which build, what error.
Strong
Title: NER export in CONLL2003 format returns empty file when spans overlap Steps:
- As tester2 open project "15-named-entity-recognition" on ENV-WEB build
afri-cloud-00204-sg7.- Ensure task 3 has two overlapping spans (PER and ORG) from
AN-NER-18.- Export → Preview, choose CONLL2003.
- Click Export.
Expected: a CONLL file listing all spans. Actual: a 0-byte file downloads; JSON and CSV formats work for the same project. Evidence: link to screenshot of the preview and the empty file.
Notice what the strong one contains that the weak one does not: the account, the project, the build, the exact data that triggers it, the exact format, and what does work. That last line halves the search space for the developer.
Rules that save time​
- One defect per cause. Before opening a new row, glance down the Defects tab; if yours looks like an existing one, reference that ID from your step instead.
- Check the web build first for anything you find on a phone. The phone builds are older (see known at the start of Round 1), so the bug may already be fixed.
- Do not diagnose. Describe what you saw, not why you think it happened. Guesses about causes send developers down the wrong path.
- Do not soften. "Seems a bit slow" hides a real problem; "the task list took 14 seconds to load with 50 tasks on a 4G connection" does not.
- Quote, don't paraphrase. Error messages, button labels and field names exactly as the screen shows them. A developer can search the code for an exact string; they cannot search for "something about permissions".