| name | scope-tamanu-release-tests |
| description | Produce a release test-impact analysis for a Tamanu version upgrade: compare two Tamanu releases and classify every functional area as Full Test, Smoke Test, or Skip, each with a short reason and the Linear card or PR reference. Use when the user wants a test plan, QA scope, regression scope, or "what to test" for a Tamanu release or upgrade, wants to compare or diff two Tamanu versions (e.g. v2.57 to v2.59), or asks which areas changed between two releases. Handles Tamanu's train-release model (release/X.Y branches vs vX.Y.Z tags) and maps changed files and PRs to Tamanu functional sections (Patient Management, Encounters/Charting, Surveys & Programs, Medications, Labs, Imaging, Appointments, Vaccinations, Sync, Settings, Reports, Admin/Permissions, Mobile, etc.). Optionally maps against a regression-testing spreadsheet's sections when one is provided. |
Scope a Tamanu release for testing
Produce a test-impact analysis for a Tamanu version upgrade: given a "from" and a "to" version, classify every functional area as Full Test, Smoke Test, or Skip, each with a one-line reason and the Linear card or PR it traces to. The output is a QA scoping table a release manager can act on directly, and it can be mapped onto an existing regression-testing spreadsheet's sections when one is supplied.
You are working inside a clone of the Tamanu repo, so read the history directly with git. The source of truth is the commit history; this skill encodes the method and the two things that trip people up โ Tamanu's branch/tag topology, and keeping the classification honest about what actually changed.
The mental model
- Resolve the two refs for the "from" and "to" versions (these are not always tags โ see the train-release model).
- Get the diff โ the commits, PRs, and changed files between the two refs.
- Map changes to sections โ group changed files/PRs by functional area via package path and conventional-commit scope.
- Classify each section โ Full / Smoke / Skip by the nature and breadth of the change, with a reason and a card/PR for every Full and Smoke.
How Tamanu releases work (read this first)
Tamanu uses a train-release model. Each minor version is cut from main as a long-lived branch release/X.Y (package version X.Y.0) and only later published as a tag vX.Y.Z once it ships. Consequences:
- A version may not be tagged yet โ it can exist only as
release/X.Y. Check tags first (git fetch origin --tags && git tag --list 'vX.Y.*'). A minor often has several patch tags (e.g. vX.Y.0 โฆ vX.Y.6): pick the latest patch tag for that minor, never an older one โ an older patch shrinks the commit range and under-scopes Full/Smoke areas. If a side has no tag yet, or the release/X.Y branch tip is ahead of the latest tag (untagged hotfixes), compare against the release/X.Y tip instead. State which ref you used for each side.
- Release branches are concurrent and can be cut at different dates, so lineage is not strictly linear;
main is usually already on the next version.
CHANGELOG.md is unmaintained โ do not rely on it. Reconstruct the change list from commit history. Commits follow conventional commits (feat(scope), fix(scope), etc.) and start with or reference the Linear card (TAM-1234, EPI-1321, KAM-463, ...) and the PR number.
Reading the diff
git fetch origin --tags
git fetch origin release/<from-minor> release/<to-minor>
# Refs: tags are global (vX.Y.Z); fetched branches are NOT local โ reference them as origin/release/X.Y.
git log --oneline --no-merges <from-ref>..<to-ref> # commits + cards/PRs
git diff --stat <from-ref>..<to-ref> # changed files by package
git diff --name-status <from-ref>..<to-ref> -- packages/database/src/migrations # A = new migration, D = deleted
Pull the Linear card and PR number out of each commit subject so every Full/Smoke row can cite one. Use origin/release/X.Y (not a bare release/X.Y) as a ref โ git fetch does not create local branches. Tamanu cherry-picks hotfixes across release branches, so <from>..<to> can list a commit that is already in the "from" side under a different SHA; when a change looks duplicated, match on the card/PR, not the raw SHA.
Tamanu functional sections
Map changes to these areas (packages: central-server, facility-server, web, mobile, shared, database):
| Section | Typical scopes / paths |
|---|
| Patient Management | patients, patient views, death/birth records |
| Encounters / Charting | encounter, notes, vitals, charts |
| Surveys & Programs / Forms | survey, programs, form question types |
| Medications / Pharmacy | medication, pharmacy, MAR, dispense |
| Labs / Imaging | labs, imaging, fhir (DiagnosticReport) |
| Appointments / Scheduling | appointments, scheduling |
| Vaccinations / Immunisations | vaccine, immunisation |
| Sync | sync, shared/sync, record sync |
| Reports | reports, report definitions |
| Admin / Permissions / Users | auth, permissions, users, roles |
| Settings | settings, config schema |
| Invoicing / Billing | invoice, billing |
| Referrals / Tasks / Locations | referral, tasks, locations, departments |
| Mobile | packages/mobile/** |
| Platform / Build / Infra | root configs, .github, deps, Node/build tooling |
Classification rubric
- Full Test โ significant new logic or broad-impact change: new features, new form/question types, changed data paths, new server routes, or framework upgrades that touch a whole surface (e.g. a React Native bump means full mobile regression). Anything that changes behaviour a user sees, or that touches data integrity.
- Smoke Test โ contained or indirect changes: single bug fixes, perf tweaks, permission gating, dependency hardening, small type changes, or build/tooling changes (verify startup and installers). Enough to confirm nothing broke, not a full regression.
- Skip โ no changes to that area.
Two signals:
- Database migrations (
packages/database/src/migrations): a new migration means a schema/data change โ Full Test the affected area plus migration/upgrade testing. No new migrations โ say so; migration testing can be skipped.
- Build/tooling churn often dominates the file count but is low functional risk. Don't let raw file counts inflate the classification โ call it out as a smoke pass over startup and installers.
Workflow
- Resolve refs. List tags; for each side pick the latest
vX.Y.Z patch tag for that minor, or the release/X.Y branch tip when it's ahead of the latest tag or nothing is tagged yet. Record which you used โ an older patch tag would under-scope the diff.
- Pull the diff.
git log/git diff between the refs; capture commit count, file count, and each commit's card/PR + scope.
- [parallel with 2] Check migrations. Diff the
packages/database/src/migrations listing between refs. Note any new files.
- Group by section. Bucket every PR/commit into a section using scope + package path. If the user supplied a regression spreadsheet, map onto its sections instead of (or in addition to) the taxonomy.
- Classify. Apply the rubric. Write a one-line reason and cite the Linear card or PR for every Full and Smoke section. List Skip sections plainly.
- Write the output (format below). Lead with the refs compared, commit/file totals, and the migration finding.
Output format
A short preamble (refs compared, totals, migration note), then three grouped tables:
## Regression Planning: v[from] -> v[to]
_Refs: <from-ref> -> <to-ref>. N commits, M files. Migrations: <new / none>._
### Full Test
| Section | Change | Card / PR |
|---|---|---|
| Medications / Pharmacy | New dispense workflow + dispensed-meds table | EPI-1321, #9939 |
### Smoke Test
| Section | Change | Card / PR |
|---|---|---|
| Labs | New resultsInterpretation field on lab requests | TAM-6840, #9997 |
### Skip
Login - Dashboard - Triage - ...
### Summary
- Full: N - Smoke: M - Skip: K
- Dominant change(s) and any risk notes.
If the user wants it as a file, offer a colour-coded spreadsheet (red = full, yellow = smoke, green = skip) and tell them the exact path it's written to. Every Full/Smoke row cites a real card or PR; never invent card numbers โ if you can't find one, cite the PR# or commit scope. If an area's link to a change is indirect, prefer Smoke over Skip and say so.
Source of truth
The Tamanu commit history is authoritative. This skill encodes a method, not a fixed answer โ the functional sections and package layout can change. If the repo disagrees with this skill, the repo wins; update the skill. Never classify an area from memory of a past release โ always read the actual diff for the versions asked about.
