Skip to content

List v5 releases on the release notes overview - #817

Merged
Ethan-Arrowood merged 3 commits into
mainfrom
fix/release-notes-overview
Nov 19, 2026
Merged

Ethan-Arrowood merged 3 commits into
mainfrom
fix/release-notes-overview

Conversation

@Ethan-Arrowood

@Ethan-Arrowood Ethan-Arrowood commented Nov 18, 2026 •

Copy link
Copy Markdown
Member

⊙ Problem

https://docs.harper.fast/release-notes labels v4 Tucker as the current release and lists no v5 versions. scripts/generateReleaseNotesData.js only matches X.Y.Z.md, but v5 notes are per minor (5.3.md) or assembled from harper and harper-pro (5.4.generated.md). The script also ran before the assembler wrote the generated files.

CONTRIBUTING's "Release Notes Process" only describes v4 per-patch files.

💡 Solution

  • Match X.Y.md and X.Y.generated.md as well as X.Y.Z.md.
  • Run prebuild.js after assemble-content.mjs in the prebuild, predev and prestart hooks.
  • Rewrite the CONTRIBUTING section to say where 5.4+, 5.0 to 5.3, and v4 notes go, and what updates automatically.

✅ Verification

  • npm run build passes. The built /release-notes page shows "Current Release - Version 5 (Lincoln)" with 5.5 down to 5.0, and the older majors are unchanged.
  • format:check and lint pass.

Drafted with Claude Opus 5.5 (my setup) and reviewed by me.

Complexity: easy

Review-Coverage: authored=claude; ran=gemini,cursor-composer,codex,gemini-carbon; late=gemini-carbon:adjudicated; adjudicated=domain; declined=cursor-grok,muse; rounds=2; full=1 @ 8fb2258

Review-Attention: read ~3m (decisions: profile-detection-by-fs-probe, dev-regen-in-assembler, contributing-drops-v4-walkthrough) @ 8fb2258

The overview at /release-notes labeled v4 Tucker as the current
release. generateReleaseNotesData.js only matched X.Y.Z.md, but v5
notes are per minor (5.3.md) or assembled (5.4.generated.md), and the
script ran before the assembler wrote the generated files.

- Match X.Y.md and X.Y.generated.md as well as X.Y.Z.md.
- Run prebuild.js after assemble-content.mjs in the pre* hooks.
- Rewrite CONTRIBUTING's "Release Notes Process", which only covered
  v4, to say where 5.4+, 5.0-5.3 and v4 notes go.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@Ethan-Arrowood
Ethan-Arrowood requested a review from a team as a code owner November 18, 2026 20:11
@github-actions
github-actions Bot temporarily deployed to docs-site-preview November 18, 2026 20:14 Destroyed
@github-actions

github-actions Bot commented Nov 18, 2026 •

Copy link
Copy Markdown

docs-site preview removed: this PR closed.

@kriszyp kriszyp left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🤖 Reviewed with Codex

Comment thread package.json
"prestart": "node scripts/assemble-content.mjs && node scripts/prebuild.js",
"start": "docusaurus start",
"predev": "node scripts/prebuild.js && node scripts/assemble-content.mjs",
"predev": "node scripts/assemble-content.mjs && node scripts/prebuild.js",

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This refreshes the release index at npm run dev startup. Subsequent local source edits go through scripts/assemble-content.mjs:317-329, which reassembles the pages without updating the JSON that the overview imports. In an in-memory run of the assembler and generator, I started with a local 5.4 note, removed its source, and invoked the watch callback. Assembly removed 5.4.generated.md, but the JSON still listed 5.4, leaving the overview pointed at a deleted page. Can you refresh the index after each successful watched assembly, and skip the write when the version list is unchanged?

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in 2de8f95. The watch callback now regenerates release-notes-data.json after each successful assembly, and the generator skips the write when the JSON is unchanged.

Drafted with Claude Opus 5.5 (my setup) and reviewed by me.

// Match version pattern in filename (e.g., "4.6.8.md")
const match = file.match(/^(\d+\.\d+\.\d+)\.md$/);
// Match "4.6.8.md", "5.3.md", or "5.4.generated.md" (assembled from harper and harper-pro)
const match = file.match(/^(\d+\.\d+(?:\.\d+)?)(?:\.generated)?\.md$/);

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Adding v5 moves Tucker into the previous-major branch in src/components/ReleaseNotesList.tsx:57-68. I rendered the component with the base and head indexes and confirmed that “Meet Tucker” changes from /release-notes/v4-tucker/tucker to /release-notes/v4-tucker/. The new destination is the release summary, while Tucker’s profile is a separate page. Can the link keep pointing to the profile when v4 moves into the archive? Alby, Penny, and Monkey have their profiles on their index pages, so those destinations should stay as they are.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in 2de8f95 and 8fb2258. The generator records hasProfilePage when the major has a <pup>.md or <pup>.mdx page, and the link uses it. Tucker links to /release-notes/v4-tucker/tucker again. Alby, Penny and Monkey still link to their index pages.

Drafted with Claude Opus 5.5 (my setup) and reviewed by me.

Comment thread CONTRIBUTING.md Outdated

### 1. Create the Release Note File
- **5.4 and later:** write a fragment in `docs/release-notes/v5-lincoln/<minor>/` of harper or harper-pro, in the PR that makes the change. [`scripts/assemble-content.mjs`](scripts/assemble-content.mjs) combines the fragments into `release-notes/v5-lincoln/<minor>.generated.md` at build time; never edit or commit that file here. The fragment format is in [harper's docs/README.md](https://github.com/HarperFast/harper/blob/main/docs/README.md#release-notes).
- **5.0 to 5.3:** one file per minor in this repo, such as `release-notes/v5-lincoln/5.3.md`. Patch releases are described in [GitHub releases](https://github.com/HarperFast/harper/releases), not here.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The last sentence says patch releases are described only on GitHub, but the checked-in minor pages also include patch highlights. For example, release-notes/v5-lincoln/5.3.md:72-74 describes a 5.3.1 change, and release-notes/v5-lincoln/5.2.md:49-55 describes 5.2.3 changes. Could you say GitHub carries the full per-patch release notes and the site groups selected changes on each minor page?

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in 2de8f95. It now says GitHub releases carry the full notes for each patch, and the minor's page highlights selected patch changes with the patch version in the heading.

Drafted with Claude Opus 5.5 (my setup) and reviewed by me.

Ethan-Arrowood and others added 2 commits November 18, 2026 23:09
…view

- Link "Meet <pup>" to the pup's own page when the major has one, so
  Tucker still links to his profile now that v4 is a previous major.
- Regenerate release-notes-data.json after each reassembly in
  `npm run dev`, and skip the write when nothing changed.
- Say in CONTRIBUTING that minor pages also highlight patch changes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Dispatch-Task: fix-Ethan-Arrowood_documentation_817-441b1ce7
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Dispatch-Task: fix-Ethan-Arrowood_documentation_817-441b1ce7
@github-actions
github-actions Bot temporarily deployed to docs-site-preview November 19, 2026 06:25 Destroyed
@Ethan-Arrowood
Ethan-Arrowood merged commit 142d0d5 into main Nov 19, 2026
13 checks passed
@Ethan-Arrowood
Ethan-Arrowood deleted the fix/release-notes-overview branch November 19, 2026 21:49
@Ethan-Arrowood
Ethan-Arrowood deployed to preview-cleanup November 19, 2026 21:49 — with GitHub Actions Active

This branch was successfully deployed

2 active deployments
preview-cleanup — 8fb2258e Deployed Nov 19, 2026 by Ethan-Arrowood via cleanup #16
docs-site-preview — 8fb2258e Deployed Nov 19, 2026 by github-actions[bot]
preview — 8fb2258e Deployed Nov 19, 2026 by Ethan-Arrowood via deploy #14
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.

3 participants