Skip to content

docs: release hygiene — roll 0.3.1, open 0.3.2, refresh stale docs#61

Merged
jinyeow merged 1 commit into
mainfrom
docs/release-hygiene
Jul 23, 2026
Merged

docs: release hygiene — roll 0.3.1, open 0.3.2, refresh stale docs#61
jinyeow merged 1 commit into
mainfrom
docs/release-hygiene

Conversation

@jinyeow

@jinyeow jinyeow commented Jul 23, 2026

Copy link
Copy Markdown
Owner

Docs + release-metadata cleanup after the Track 2 foundations landed (#57, #58, #59, #60). No code change; the only functional line is the version prefix.

Two real defects, not just staleness

  • v0.3.1 shipped without a CHANGELOG section. The tag sits on the Track 1 commit (refactor(tui): Track 1 — IUiPost seam, VmGuard dedup, DiffPaneComposer extraction (#39, #40, #41) #54), and the [Unreleased] block is that release's content — verified: git show v0.3.1:CHANGELOG.md still reads ## [Unreleased], and nothing has touched the file since. Rolled into a dated ## 0.3.1 — 2026-07-23.
  • VersionPrefix was left at 0.3.0 through the 0.3.1 release, so every local and branch build reported 0.3.0-alphabelow the released 0.3.1, inverting the guarantee its own comment makes ("a dev build can't be mistaken for, or installed over, a released one"). Bumped to 0.3.2, with the comment now saying to keep it in step with the newest CHANGELOG section. Verified empirically: dotnet run -c Release -- --version0.3.2-alpha+c902111.

New: 0.3.2 section

Honest about what it is — no user-facing change. It carries the dependency bumps (#37, #38) and the four internal foundations for the list + preview workspace (ADR 0024): the pure detail formatters, WorkspaceLayout, the typed ADR 0008 invariants (SingleFlightCache<K,V> / Published<T>), and WorkspaceViewModel. The workspace itself is not enabled — Tab still falls back to today's behaviour until #48 makes the preview visible.

Stale docs refreshed against the code

  • README status line — said v0.1.0, three releases behind — and the test count (808 → 1,208, measured on merged main: 375 Core + 833 Tui).
  • README dev-install examples that pinned the old 0.3.0 prefix (0.3.0-alpha, 0.3.0-local1, 0.3.0+<sha>).
  • CLAUDE.md suite size (~750~1,200).
  • The UAT checklist's --version expectation, which contradicted shipped behaviour on both counts: it expected 0.1.0 and "no git-hash suffix", but Program.InformationalVersion() has deliberately kept the 7-char +<sha> since 0.3.0. Rewritten to describe both the release and dev-build shapes.

Deliberately not touched

  • HANDOFF.md — its staleness is structural, not a version string: it references a long-dead branch (claude/azure-devops-tui-97d16e) and carries real org names that are pending your scrubbing decision. Fixing only the version would leave the misleading parts in place; its fate is a separate call.
  • Historical CHANGELOG sections and docs/PLAN.md milestone checkboxes — those are records, correctly frozen.
  • docs/testing/manual-verification.md's run-record table still shows 0.1.0 / 0e103df in an otherwise blank form. Left as-is; it's a record of a past run, not an instruction.

Clean CI-style Release build (--no-incremental, ContinuousIntegrationBuild=true): 0 warnings, 0 errors. Suite 1,208 green.

Follow-up: tag v0.3.2 once this merges, so the tagged commit carries the matching CHANGELOG and prefix.

The v0.3.1 tag shipped without its own CHANGELOG section: the [Unreleased]
block was the Track 1 (#54) content that release carried. Roll it into a dated
0.3.1 section and open 0.3.2 for the flagship foundations (#57/#58/#59/#60) and
the dependency bumps — all internal, no user-facing change.

VersionPrefix was left at 0.3.0 through the 0.3.1 release, so every local and
branch build reported a version BELOW the last release, inverting the guarantee
the surrounding comment makes. Bump it to 0.3.2 and say so in the comment.

Also refresh what had gone stale against the code:
- README status (v0.1.0, three releases behind) and test count (808 -> 1,208)
- README/dev-install version examples, which pinned the old 0.3.0 prefix
- CLAUDE.md suite size (~750 -> ~1,200)
- the UAT checklist's `--version` expectation, which contradicted shipped
  behaviour on both counts: the version is no longer 0.1.0, and the output has
  carried its +<sha> source revision since 0.3.0

HANDOFF.md is left alone deliberately: its staleness is structural (a dead
branch reference, plus org names pending a scrubbing decision), not a version
string.
@jinyeow
jinyeow merged commit 0a93df7 into main Jul 23, 2026
5 checks passed
@jinyeow
jinyeow deleted the docs/release-hygiene branch July 23, 2026 22:49
@jinyeow jinyeow mentioned this pull request Jul 23, 2026
jinyeow added a commit that referenced this pull request Jul 24, 2026
The root handoff was structurally stale, not cosmetically: its build+install
block pinned the long-dead branch claude/azure-devops-tui-97d16e and
--version 0.1.0, and its "current state" reported 518 tests against a suite
that is now 1208. PR #61 left it alone for exactly that reason.

Every heading was a duplicate of a doc that owns the content better —
README (install/config/auth), CLAUDE.md (house rules, architecture, the TDD
loop), docs/testing/manual-verification.md (the 94-item UAT checklist), and
ADRs 0011/0015 (the ADO route caveats). The two open threads no repo doc
owned were migrated out before deletion. Nothing in the repo referenced the
file.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant