Retire the README 'New in vX.Y.Z' stack in favour of a version-free feature summary #44

New issue

Open

opened 2026-09-14 04:47:44 +00:00 by agent-pi · 1 comment

agent-pi commented

2026-09-14 04:47:44 +00:00

Collaborator

Problem

The README opens with seven dense **New in vX.Y.Z** paragraphs before any actionable content. The pattern has three structural defects:

Version attribution is guesswork. Labels are written when the feature lands, before the release that ships it is decided — the current top entry announces "New in v1.8.0" for an unreleased change. This spawned repeated review findings: WuMing re-raised version-attribution mismatches six times across PRs #41 and #43.
Completeness drifts by design. Releases without hand-written prose simply vanish from the stack — v1.7.x and v1.1.0 have no entries, and nothing flags the gap.
It duplicates history kept better elsewhere. "What's new" already lives in CHANGELOG.md, docs/reference/changelog.md, the version-history list in docs/usage/command-reference.md, and the fediverse release thread. The README copy is the only one maintained by hand per change, and the worst of the five.

The durable content of those paragraphs is the feature descriptions themselves, not the dates they shipped.

## Problem The README opens with seven dense `**New in vX.Y.Z**` paragraphs before any actionable content. The pattern has three structural defects: 1. **Version attribution is guesswork.** Labels are written when the feature lands, before the release that ships it is decided — the current top entry announces "New in v1.8.0" for an unreleased change. This spawned repeated review findings: WuMing re-raised version-attribution mismatches six times across PRs #41 and #43. 2. **Completeness drifts by design.** Releases without hand-written prose simply vanish from the stack — v1.7.x and v1.1.0 have no entries, and nothing flags the gap. 3. **It duplicates history kept better elsewhere.** "What's new" already lives in `CHANGELOG.md`, `docs/reference/changelog.md`, the version-history list in `docs/usage/command-reference.md`, and the fediverse release thread. The README copy is the only one maintained by hand per change, and the worst of the five. The durable content of those paragraphs is the feature descriptions themselves, not the dates they shipped.

agent-pi commented

2026-09-14 04:47:59 +00:00

Author

Collaborator

Plan of attack (small README-only PR, to land after #43 merges so the range-scanning announcement isn't lost mid-review):

Replace the seven **New in vX.Y.Z** paragraphs with a compact version-free Features bullet list — one line per capability with its indicator emoji: update checks (⚠️/❌/💥), constraint-range advisories (🚨), latest-release advisory feed (🔒), license compliance (⚖️), supply-chain quarantine (⏳), library mode, JSON output, [tool.zaojun] config, caching, private indexes. Detail stays in docs/usage/command-reference.md (already linked).
Keep everything else: badges, intro sentence, install sections.
History stays where it belongs: CHANGELOG.md, docs/reference/changelog.md, the command-reference version history, and the release thread. No version labels in the README going forward — the "New in" pattern is retired, which also removes the version-attribution review churn permanently.

Plan of attack (small README-only PR, to land after #43 merges so the range-scanning announcement isn't lost mid-review): - **Replace** the seven `**New in vX.Y.Z**` paragraphs with a compact version-free **Features** bullet list — one line per capability with its indicator emoji: update checks (⚠️/❌/💥), constraint-range advisories (🚨), latest-release advisory feed (🔒), license compliance (⚖️), supply-chain quarantine (⏳), library mode, JSON output, `[tool.zaojun]` config, caching, private indexes. Detail stays in `docs/usage/command-reference.md` (already linked). - **Keep** everything else: badges, intro sentence, install sections. - **History** stays where it belongs: `CHANGELOG.md`, `docs/reference/changelog.md`, the command-reference version history, and the release thread. No version labels in the README going forward — the "New in" pattern is retired, which also removes the version-attribution review churn permanently.