Correct or retire a published case

Correcting a published case is a normal part of running one. A rubric level reads badly, a starter test is flaky, the situation needs a sentence. Fito has a route for that, and it keeps the case’s identity: learners already working keep the version they pinned, and new learners get the correction.

What decides the route is not how big the change is. It is whether the change touches the case’s knowledge references.

The two routes

What changed	Route
Starter code, wording, rubric phrasing, descriptions, the quiz	A new version of this case
The knowledge components or Bloom levels in the learning objectives, the prerequisites or the rubric	A new case, and this one is retired

The second route exists because the reference set is frozen once a case is published. See The reference set.

Decide which route you are on before you start editing. A reference-changing edit discovered at publish time is work thrown away.

Note

The quiz is not part of the frozen set. You can add, change or remove quiz questions in a new version.

Check the case out

/fito-case-edit <case-id>

<case-id> is the <id> from the case’s /cases/<id> URL. Add --dir <target> to choose where it lands; the default is ~/.fito/authoring/<case-id>.

This clones your own repository — not a fork — and checks out main, the development branch. You do not need to be logged in for a published case.

It then reads you the orientation brief: the currently published version, the latest change description, and a summary of the .case/ tree.

Two warnings do not stop it:

• The gh account does not own the case repository. Editing locally is fine. Publishing needs write access to the repository, which an organisation member may well have.
• The cloned .case/ tree does not read cleanly. Route that through the validator before editing.

Four things refuse it outright: a draft case, a deprecated case, an unknown id, and a target directory that is not empty. It never overwrites anything.

Edit on main

All editing happens on main. The published vX.Y.Z and case/solution-vX.Y.Z refs are never rewritten.

Adjust the source and the .case/ contract, re-run the validator until it is clean, and commit. Committed edits on main lose nothing by waiting.

Publish the new version

1. Agree the new version number. It must be strictly greater than the published one. A patch for a correction and a minor for a perfection is a sane default; the number is yours to choose.

2. Set that version in all three places, or the publish refuses:

   • .case/manifest.yaml — version:
   • .case/manifest.yaml — submission.target_branch: (a learner’s pull request targets the frozen version branch)
   • .case/solution.yaml — branch: case/solution-vX.Y.Z

3. Rebuild the exemplar branch for this version: start from the previous version’s solution branch and re-apply it onto the updated main. That is source work, done outside Fito.

4. Approve the change description — what changed and why, a few sentences. It is served with the case and shown at the next checkout, and it is written to .authoring/change-description.md. Revise the storefront description too if the correction changes what a learner should read before enrolling.

5. Commit everything, then run the publish from the checkout:

   /fito-publish-case

   It detects that this directory is an already-published case and takes the update path by itself.

When the version publish stops

Nothing is registered until the final call succeeds, and your local tree is never modified, so every one of these is safe to fix and re-run.

What you see	What it means	What to do
“The knowledge-reference set is frozen across versions, and this tree changes it”	The edit is on the other route	Revert the reference change if it was unintended — or design the successor case and retire this one
“.case/manifest.yaml is stale for the new version”	submission.target_branch still names the old version	Set it to the new version, commit, re-run
“.case/solution.yaml is stale for the new version”	branch: still names the old version	Set it, build the exemplar on it, commit, re-run
“manifest.version is still …” or “must be strictly greater than the published …”	The version did not move, or moved backwards	Bump all three fields, re-validate, commit, re-run
“The local solution branch … does not exist”	The exemplar for this version is not built	Rebuild it from the previous version’s solution branch
A rejection from the Fito server	Often a failed reachability ping	An update’s push needs write access to the case repository. Check it on GitHub, then re-run

The frozen-reference stop itemises exactly what was added and what was removed. Read that list before deciding — it is the difference between a typo and a real change of scope.

After it succeeds

You get the previous and new versions, the web URL, and a note that prior learners keep their pinned versions while /fito-case-open <case-id> now serves the new one.

Your checkout is refreshed too: the new tags and origin/… refs are local. If that last step reports a ⚠, the version is published and only the refresh failed — pick the refs up later with git fetch origin --tags.

Retire a case

Retiring a case means marking it deprecated. A deprecated case:

• disappears from the catalogue, so no new learner finds it;
• is still served at its own /cases/<id> URL, with a notice;
• still accepts submissions from learners who already started, so nobody is stranded mid-case.

That last point is why retiring is safe. You are closing the door, not emptying the room.

The control is on the case’s own page:

1. Open the case and sign in as its owner or as an admin. Retire this case appears above the case cover. Nobody else sees a control there.

2. Click Retire this case. The confirmation names what the change costs and what it leaves alone: the case leaves the catalogue and stops appearing in discovery, while learners already working on it keep their checkout, their submissions and their assessments.

3. Click Retire this case again to confirm. The deprecation notice appears on the page, without a reload.

An admin can retire any case. The owner is the account that registered the case. It is fixed at registration and never reassigned, so without that reach a case would outlive its creator’s access with nobody able to retire it. An admin uses the same control, and the same rule guards the write itself.

Do not set status: deprecated in .case/manifest.yaml instead. The field exists, and the validator will even ask you for a deprecated_reason beside it — but nothing on the Fito server ever reads it. Retirement is a state the server holds, not something the repository declares. Editing the manifest changes nothing except your own tree, and the published vX.Y.Z refs cannot be rewritten anyway.

Three things refuse the write: a case that does not exist, an account that is neither the owner nor an admin, and a case that is a draft or is already retired. The confirmation names the reason in words.

Bring a retired case back

Retiring is reversible. Reinstating moves the case from deprecated back to published, and it returns to every read that hid it: the catalogue, the Used in cases list on a knowledge component, the Do these first recommendation on another case, and the checks that /fito-case-open, /fito-case-edit and /fito-publish-case run before they touch a case. Submissions, enrollments, curation votes and the published vX.Y.Z refs are untouched, because only the status changes.

The control sits where the retire control was:

1. Open the retired case and sign in as its owner or as an admin. Reinstate this case appears above the case cover.

2. Click Reinstate this case, read the confirmation, and click it again. The deprecation notice goes, without a reload.

Check for a successor first

Nothing records whether another case replaced this one. A case is usually retired because a reference-changing correction forced a successor case into existence, and no link ties the two together — so Fito cannot detect the clash, and the write does not refuse it. If a successor exists, reinstating puts both cases into discovery at once, competing for the same learners. Only you can tell whether that is right.

The same three refuse it, with the last one reversed: a case that is not retired.

What’s next

• Design a case — where a successor case starts.
• Publish a case — the first publish, for comparison.