trace-first-starter

HL — TFW-6: Versioning, Changelog, and tfw-update Workflow

Date: 2026-03-12 Author: Coordinator (AI) Status: 🔵 HL — Awaiting review (v2 — post-discussion)

1. Vision

TFW is a living framework. The starter repo (trace-first-starter) evolves — new templates, new workflows, convention changes, bug fixes. But downstream projects that forked or copied .tfw/ have no mechanism to know what changed, what version they’re on, or how to safely update.

This task introduces:

“If you can’t tell what version you’re running, you can’t tell what’s missing.”

2. Current State (As-Is)

Aspect Status
Version tracking ❌ None — .tfw/README.md mentions “v3” in prose, no machine-readable version
Changelog ❌ None — evolution history is narrative in .tfw/README.md §Evolution
Update mechanism ❌ None — manual diff of entire .tfw/ directory
Release process ❌ None — no workflow for cutting versions
Release context ❌ None — no project-level release strategy document
Downstream awareness ❌ — forked projects have no way to know upstream changed
Adapter sync ❌ — .agent/workflows/ are copies of .tfw/workflows/, no version check

Files Involved (current)

| File | Role | Relevant? | |——|——|———–| | .tfw/README.md | Philosophy + evolution narrative (v1→v2→v3) | Version info buried in prose | | .tfw/PROJECT_CONFIG.yaml | Per-project config | No version field | | .tfw/conventions.md | Rules, required artifacts | No RELEASE.md entry | | .tfw/init.md | Setup guide | Describes copying .tfw/, no update/release guidance | | .agent/workflows/ | Antigravity adapter copies | Copies of .tfw/workflows/ — can drift |

3. Target State (To-Be)

Aspect Target
Version tracking VERSION file in .tfw/ with semver (MAJOR.MINOR.PATCH)
Changelog CHANGELOG.md in .tfw/ — structured, per-version, with categories
Project version tracking tfw_version field in .tfw/PROJECT_CONFIG.yaml records installed version
Update workflow .tfw/workflows/update.md — step-by-step upgrade process for downstream projects
Release workflow .tfw/workflows/release.md — canonical release process (general, any project)
Release context RELEASE.md (root, optional) — project-specific release strategy. Template in .tfw/templates/RELEASE.md
Adapter workflows .agent/workflows/tfw-update.md + .agent/workflows/tfw-release.md
Docs integration init.md mentions versioning + RELEASE.md; KNOWLEDGE.md updated

Version Scheme

MAJOR.MINOR.PATCH

CHANGELOG Format

# TFW Changelog

## [0.3.1] — 2026-03-12
### Added
- `CHANGELOG.md` — version history
- `VERSION` file — machine-readable version
- `tfw-release` workflow — canonical release process
- `tfw-update` workflow — structured upgrade process
- `RELEASE.md` template — optional release context artifact
### Changed
- `PROJECT_CONFIG.yaml` — added `tfw_version` field
- `init.md` — added version tracking and release guidance

Categories: Added, Changed, Deprecated, Removed, Fixed.

RELEASE.md Design

Template (.tfw/templates/RELEASE.md) — a scaffold with guiding questions:

This project’s instance — fully populated with TFW framework release context:

tfw-release Workflow (canonical, general)

Lives in .tfw/workflows/release.md. General steps applicable to any project:

  1. Read RELEASE.md for project-specific context
  2. Review what changed since last release (Task Board, git log, RF files)
  3. Decide version bump type (consulting RELEASE.md strategy)
  4. Update changelog
  5. Update version marker
  6. Tag/commit

tfw-update Workflow (canonical, for downstream consumers)

Lives in .tfw/workflows/update.md. For projects consuming TFW:

  1. Read current version from PROJECT_CONFIG.yaml → tfw_version
  2. Read target version from upstream .tfw/VERSION
  3. Show CHANGELOG diff — all entries between current and target
  4. Categorize changes:
    • 🟢 Auto-apply — new files, new workflows (no project customization risk)
    • 🟡 Manual merge — changed templates, conventions (project may have customized)
    • 🔴 Breaking — removed/renamed files, structural changes
  5. Generate update checklist — concrete file-by-file actions
  6. Update tfw_version in PROJECT_CONFIG.yaml after completion
  7. Re-sync adapter copies (.agent/workflows/ etc.) from .tfw/workflows/

4. Phases

Phase A: Core Versioning Infrastructure 🔴

Phase B: Workflows 🔴

Phase C: Documentation & Traces 🟡

5. Definition of Done (DoD)

6. Definition of Failure (DoF)

On failure: Simplify. Version can be a single number. CHANGELOG can be a flat list. RELEASE.md scaffold can be 5 lines.

7. Principles

  1. Plain text, no tooling — VERSION is a text file, CHANGELOG is Markdown. No scripts needed to read or compare.
  2. Retroactive completeness — CHANGELOG covers v1, v2, v3 history so the record is complete from day one.
  3. Downstream safety — tfw-update MUST distinguish between files safe to overwrite and files the project has customized. Never silently destroy project-specific changes.
  4. Optional over mandatory — RELEASE.md is optional (like KNOWLEDGE.md). Projects that don’t do releases skip it. No overhead.
  5. General over specific — tfw-release workflow contains general release steps. Project-specific context lives in RELEASE.md, not in the workflow.
  6. Adapter parity — every canonical workflow in .tfw/workflows/ gets a corresponding adapter copy.

8. Dependencies

Dependency Status
TFW-4 (framework cleanup) 🟡 TS — in progress but not blocking
TFW-5 (KNOWLEDGE + tfw-docs) ✅ DONE

9. Risks

Risk Probability Impact Mitigation
Retroactive CHANGELOG inaccurate Medium Low Cross-check with .tfw/README.md §Evolution and task RFs
Projects forget to update tfw_version Medium Medium tfw-update workflow includes version bump as final step
RELEASE.md template too vague Medium Low Populate this project’s RELEASE.md as a real example; link from template
Breaking changes hard to communicate Low High CHANGELOG uses clear ### Breaking section; tfw-update flags 🔴 items
*HL — TFW-6: Versioning, Changelog, and tfw-update Workflow 2026-03-12 (v2)*
This site is open source. Improve this page.