# TTC-113 — Version history and rollback

Version every behavioral change with a focused diff, rationale, tests, and an exact recovery path to a known approved state.

Level: practitioner · Version: 1.0.0 · Last reviewed: 2026-10-03
Review status: reviewed

## 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 fictional 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.

## Reusable 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.

## Observable 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.

## Next review
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.

## Copyable material
```text
# TTC-113 — Version history and rollback
Objective: Make behavior changes attributable, testable, and recoverable without erasing history.
Procedure: Create a focused diff; record reason, source, owner, version, approval, tests, recovery basis, and exact scoped rollback.
Required evidence: Keep before/after identifiers plus acceptance, regression, and rollback-rehearsal results.
Boundaries: Do not call destructive or externally irreversible effects rollback-safe; preserve unrelated concurrent state.
Completion test: The change and its revert can each be explained and reproduced, and both leave the repository consistent.
Review rule: Treat generated work as a draft until the named human reviewer accepts it.
```

## Primary sources
- Git project: git-revert: Revert some existing commits — https://git-scm.com/docs/git-revert
- Semantic Versioning project: Semantic Versioning 2.0.0 — https://semver.org/spec/v2.0.0.html

Canonical URL: https://teachthecompany.com/school/version-history-and-rollback/
Related established guide: https://teachthecompany.com/version-control-for-ai-agents/