Bugs and incidents
How bugs are reported, rated and triaged, where they live, the response targets from build to production, the incident and hotfix process, and the on-call duty during the pilot.
What is a bug
A bug is behaviour that contradicts the SRS, the API contract, a validated design or an acceptance criterion — or a crash, a data loss or a security problem. Behaviour the SRS does not describe is not a bug: it is a clarification or a change request. A gap between a build and its Claude Design frames is a design-qa issue (design QA).
Reporting a bug
The issue template of hoco (.github/ISSUE_TEMPLATE/bug_report.md) holds these sections; hoco-mobile uses the same with the device fields. Severity and priority are labels set at triage, not fields the reporter fills in.
Title: [RA-18] Checkout shows the détail price to a demi-gros reseller
## What happened
## Where
- App and version: reseller app 0.4.0 (build 112) | back-office | API
- Environment: local | staging | pre-production | production
- Screen or operation: RA-18 · POST /cart/checkout
- Device (mobile): Samsung Galaxy A15, Android 14, weak 4G
- Account: REV-000123 (test reseller, customer type DEMI_GROS)
## Steps to reproduce
1.
## Expected — link the requirement or acceptance criterion
PRC-01: the reseller's customer type selects the price.
## Actual — include the requestId of any API error
## Screenshots, recording, logs- One bug per issue. The title starts with the screen id or the op id in brackets.
- API errors: paste the
requestIdfrom the error envelope — it finds the log line. - Never paste tokens, passwords, or customers' personal data; mask phone numbers.
- HOCO does not use GitHub. HOCO reports in the client WhatsApp group or by e-mail (what, where, when, which user, a screenshot), or in the acceptance sheet during the recette. Whoever is on triage files the issue the same working day, labels it
found-by-hoco, and replies with the issue number.
Severity
Severity is the impact. Core flows (V1): sign-in and sign-up, guest browsing, catalog and prices, cart and checkout, order confirmation and live tracking, after-sales claims and returns, tour start, visits, check-in and closing, prospect sign-up and invitation, the assisted first order, offline sync, permissions.
| Severity | Definition | Examples |
|---|---|---|
| Blocker | A core flow is impossible with no workaround; data lost or corrupted; a security or privacy breach; the app crashes on start | Nobody can sign in; checkout fails for everyone; offline visits disappear after sync; a delegate sees another zone's resellers; stock quantities or purchase prices exposed to resellers |
| Critical | A core flow broken for some users or only with a painful workaround; wrong money, stock or status figures | The wrong customer-type price applied; an order goes to preparation without the back-office confirmation; a cancelled order does not release its stock; order status changes not pushed |
| Major | A secondary function broken, or a core flow degraded with an easy workaround | An export fails; a catalog filter returns wrong counts; a map pin is offset |
| Minor | Cosmetic, copy, small annoyance | A truncated label, a wrong icon, a typo |
Acceptance rule (cahier §12: « les anomalies bloquantes sont corrigées », OPS-05): the PV is signed with no Blocker and no Critical open. Open Majors are listed in the PV as reserves, each with a fix version.
Priority
Priority is the urgency, set at triage.
| Priority | Meaning | Default for |
|---|---|---|
| P1 | Now — the owner drops current work | Blocker |
| P2 | This week, or the next candidate | Critical |
| P3 | Planned in a coming release | Major |
| P4 | Backlog — may never be done | Minor |
Triage moves a priority up or down with a reason: a Major on the pilot's main flow becomes P2; a Critical in a feature nobody uses yet becomes P3.
Response targets
Working hours unless stated. Acknowledged = an owner is assigned and the reporter is answered.
| Severity | Build (staging) | Acceptance (pre-production) | Pilot (production, limited users) | Production (after generalisation) |
|---|---|---|---|---|
| Blocker | Fixed within 1 working day | Acknowledged 1 h · fix or workaround the same day · new candidate the next morning | Acknowledged 30 min in on-call hours · mitigated 4 h · fixed 1 working day | Acknowledged 1 h · mitigated 4 h · fixed 1 working day |
| Critical | Fixed within 2 working days | Acknowledged 2 h · fixed in the next candidate, 2 working days at most | Acknowledged 2 h · fixed within 2 working days | Acknowledged 4 h · fixed within 3 working days |
| Major | In the current task, or the next week | Fixed before the PV, or a reserve with a fix version | Fixed during the pilot, within 5 working days | Next planned release |
| Minor | Backlog | Reserve or backlog | Collected for LCH-04 and MOB-18 | Backlog |
Assumption — the production column is the team's proposal for the maintenance contract: the cahier leaves the warranty period, the support delays and the priority levels to be defined (cahier §13.4, OPS-04). It is settled in the decision register before go-live.
When each phase applies:
| Task | Name | Owner | Phase | Dates | Effort |
|---|---|---|---|---|---|
QA-03 | Functional test campaign — scripted scenarios on staging | Akram | P1 | Sun 20 Dec → Mon 21 Dec | 2 d |
QA-01 | End-to-end integration testing on staging | Anis | P2 | Wed 23 Dec → Thu 24 Dec | 1.5 d |
QA-02 | Client acceptance (recette) on pre-production & PV | Anis | P2 | Thu 24 Dec → Mon 28 Dec | 2 d |
3 tasks · 5.5 d of open effort. Dates are computed — Sunday–Thursday weeks, holidays excluded.
| Task | Name | Owner | Phase | Dates | Effort |
|---|---|---|---|---|---|
LCH-01 | Production go-live — deploy, import data, monitoring | Anis | P2 | Mon 28 Dec → Tue 29 Dec | 1 d |
LCH-02 | Training — administrators, managers and pilot delegates | Anis | P2 | Tue 29 Dec → Wed 30 Dec | 1 d |
LCH-03 | Pilot (2 weeks) — support, daily triage, hotfixes (Anis) | Anis | P2 | Wed 30 Dec → Thu 14 Jan | 10 d |
LCH-03B | Pilot (2 weeks) — mobile support & hotfixes (Imad) | Imad | P2 | Thu 31 Dec → Thu 14 Jan | 10 d |
LCH-04 | Pilot improvements — server & back-office | Anis | P3 | Thu 14 Jan → Tue 19 Jan | 3 d |
LCH-05 | Generalisation roll-out — waves by zone, public store release | Anis | P3 | Wed 20 Jan → Thu 21 Jan | 1.5 d |
6 tasks · 26.5 d of open effort. Dates are computed — Sunday–Thursday weeks, holidays excluded.
Triage
- Build: Anis triages new issues of both repositories every working day by 11:00 — severity, priority, owner, milestone, labels. Imad covers
hoco-mobilewhen Anis is out. - Acceptance and pilot: a 15-minute triage call every working day at 16:30 — the team, plus HOCO's pilot lead during the pilot (LCH-03). P1s are handled when they arrive, not at triage.
- Every Wednesday sync: open Critical and Major issues;
needs-infoissues older than 3 days (closed when no answer comes within 5 working days).
| Label | Values |
|---|---|
| Type | bug, design-qa, design-change, change-request, incident, enhancement, tech-debt |
| Severity | sev:blocker, sev:critical, sev:major, sev:minor |
| Priority | P1, P2, P3, P4 |
| App | app:server, app:dashboard, app:web, app:docs · app:reseller, app:delegate |
| Environment | env:staging, env:preprod, env:prod |
| Flow | needs-triage, needs-info, blocked, cross-repo, regression, found-by-hoco |
Every release has a GitHub milestone named after its version; a bug to fix in it is assigned to that milestone.
Where bugs live
- In the repository whose code must change: API, back-office, reseller web and docs in
hoco; the reseller and delegate apps inhoco-mobile. - Not sure? Open it in
hocowithneeds-triage. The two repositories belong to different accounts, so GitHub cannot transfer an issue between them: triage re-creates it in the other repository, links both and closes the first. - Cross-repository bugs (both sides must change): one issue per repository, linked both ways (
AnisBetehi/hoco#42and thehoco-mobileissue number), labelcross-repo. The server or contract side is fixed first. - A contract mismatch found in integration is fixed by the side that differs from the contract. If the contract is wrong, a contract PR fixes it (API-contract workflow).
Incidents in production
An incident is production unavailable, a Blocker or Critical in production, or a security event.
Detect — a Sentry alert, the uptime monitor, a report from HOCO, or our own checks.
Acknowledge — the on-call person posts INCIDENT: <one line> in the team group and opens an issue labelled incident (severity, start time, symptoms). The incident lead is Anis for the server, data, back-office and web; Imad for the apps and the stores.
Mitigate — restore the service first: roll back, switch a flag off, turn on maintenance mode, raise the minimum app version, block an abusive client. The root cause comes after.
Communicate to HOCO — Anis, in the client group then by e-mail for a Blocker. First message within 30 minutes of the acknowledgement: what is affected, for whom, the workaround, the time of the next update. Updates every 2 hours until resolved. A closing message says what users must do (for example, update the app).
Resolve — the fix goes through the hotfix flow, is verified in production, and monitoring is watched for a working day.
Postmortem — within 3 working days for every Blocker and Critical. Blameless. Its actions become issues or tasks; a French summary goes to HOCO.
# Postmortem — INC-YYYY-NN — <title>
Severity: Blocker | Critical · Duration: <start → end, Africa/Algiers> · Lead: <name>
## Impact
Who was affected, how many, what data, what money.
## Timeline
HH:MM — detected by … · HH:MM — acknowledged · HH:MM — mitigated · HH:MM — resolved
## Root cause
## What went well / what did not
## Actions
- <owner> — <action> — <issue or task id>Hotfix flow
Server, back-office, reseller web (hoco):
hotfix/x.y.zfrom the production tag onmaster.- Fix, with a test that reproduces the bug.
- PR into
master, labelhotfix. Imad reviews it if he is reachable within the hour; otherwise Anis self-reviews and Imad reviews after the merge, the next working day. - Tag
vX.Y.Z; production deploy — allowed outside the deploy windows for a P1. - Merge
masterback intodev, and into an openrelease/*if there is one.
Mobile apps (hoco-mobile):
- Halt the staged rollout first if the faulty version is rolling out.
hotfix/x.y.zfrom the production tag; fix with a test.- Anis reviews when the fix touches a sensitive path (who reviews what).
prodbuild → Play internal testing (15-minute smoke test) → closed track (pilot) or production.- If the bug corrupts or loses data, raise the minimum version in BO-66 so the faulty version is forced to update.
On-call during the pilot
The pilot runs two calendar weeks in production with a limited group of delegates and resellers (cahier §14, phase 9 Pilote). Anis (LCH-03) and Imad (LCH-03B) are on call for its whole duration.
| Item | Rule |
|---|---|
| Hours | Sunday–Thursday 08:00–19:00 (the field day and the tour closings). Friday and Saturday: P1 only, by phone. During Ramadan, the field hours HOCO announces (Ramadan) |
| Primary | Anis — server, back-office, data, imports. Imad — apps, store, devices |
| Backup | Each is the other's backup for acknowledging and communicating |
| Akram | Rides along with pilot delegates and interviews resellers (DQA-08); reports UX findings, not on call |
| HOCO | The pilot lead has both phone numbers and calls only for a P1; everything else goes to the client group |
| Every morning, before 08:30 | Check Sentry, sync errors, failed jobs and the outbox backlog |
| Every afternoon, 16:30 | Triage call: KPIs of the day and new defects |
After the pilot, on-call ends. Production support then follows the maintenance contract, still to be agreed with HOCO (see the assumption under response targets).
Definition of done
When a task may start (definition of ready) and when it is finished, per type of work — server endpoint, back-office page, mobile screen, design screen, docs page and database migration.
Change requests and decisions
The cahier's scope clause turned into a process: what counts as a change, how a request becomes a written decision, how the plan is updated, how the decision register works, and when HOCO signs.