{"id": "TTC-113", "slug": "version-history-and-rollback", "title": "Version history and rollback", "level": "practitioner", "summary": "Version every behavioral change with a focused diff, rationale, tests, and an exact recovery path to a known approved state.", "learning_outcome": "Review, activate, and safely revert a scoped rule change while preserving a complete explanatory history.", "explanation": "History is useful when each change is understandable and recoverable. Give content a stable identity and a version, separate proposed from active, and review the actual diff. Capture the reason, source, author or owner, approval, and test evidence. Before activation, define rollback that affects only the changed scope and does not overwrite unrelated later work. Reverting creates a new historical event; it should not erase the failed revision. Practice recovery on a disposable copy when consequences are material, and re-run the same acceptance checks after rollback.", "worked_example": "Fictional case: version 1.3.0 of a library reply rule accidentally removes the requirement to cite opening hours. Tests catch the omission. The owner reverts that commit, producing 1.3.1, and verifies that citations return without restoring unrelated template changes. The rejected diff remains visible.", "exercise": "Create version 1.0.0 of a fictional rule and tests. Propose one behavior change with a diff and release note, introduce a deliberate failure, then use a scoped revert on a disposable copy. Record before/after hashes and run both acceptance and unrelated-state checks.", "success_criteria": ["The active version, proposed change, rationale, reviewer, and test evidence are independently visible.", "Rollback restores the prior behavior while preserving unrelated data and later independent work.", "Post-rollback acceptance and regression checks pass and the failed revision remains auditable."], "limitations": ["Version numbers communicate change shape only when a project defines and follows its compatibility contract.", "Rollback may be unsafe for destructive data changes or external effects; those require purpose-built recovery."], "prerequisites": ["TTC-111", "TTC-112"], "next_lessons": ["TTC-117", "TTC-120"], "copyable_material": "# TTC-113 \u2014 Version history and rollback\nObjective: Make behavior changes attributable, testable, and recoverable without erasing history.\nProcedure: Create a focused diff; record reason, source, owner, version, approval, tests, recovery basis, and exact scoped rollback.\nRequired evidence: Keep before/after identifiers plus acceptance, regression, and rollback-rehearsal results.\nBoundaries: Do not call destructive or externally irreversible effects rollback-safe; preserve unrelated concurrent state.\nCompletion test: The change and its revert can each be explained and reproduced, and both leave the repository consistent.\nReview rule: Treat generated work as a draft until the named human reviewer accepts it.", "sources": [{"title": "git-revert: Revert some existing commits", "publisher": "Git project", "url": "https://git-scm.com/docs/git-revert"}, {"title": "Semantic Versioning 2.0.0", "publisher": "Semantic Versioning project", "url": "https://semver.org/spec/v2.0.0.html"}], "version": "1.0.0", "reviewed_on": "2026-10-03", "review_status": "reviewed", "next_review_criteria": "The project's version policy, activation model, or recovery mechanism changes.; A cited primary source is materially revised, replaced, or becomes unavailable.; Repeated learner results show that the exercise or success criteria are ambiguous.", "canonical_aliases": ["/version-control-for-ai-agents/"], "canonical_url": "https://teachthecompany.com/school/version-history-and-rollback/"}