add-changelog-entry · git:20261110.451b27e · 2026-11-10 · sha256 024ac84a70a86986
add-changelog-entry git:20261110.451b27eA
Immutable. This exact content never changes and is served at /api/v1/blob/024ac84a70a86986.
No tool to install first
claude plugin marketplace add https://markdownregistry.com/mp/a/art_ni26mfuthiuonv4v/024ac84a70a86986f353862dea9f29dd8192bc4c6d09abbc6946f678f7f8b1f4.json
Then /plugin install add-changelog-entry@markdownregistry-ni26mfuthiuonv4v in Claude Code. It installs this exact version, the one graded A here, pinned to the commit it was graded at, and leaves it there.
---
name: add-changelog-entry
description: Write a new release entry on the public Duct changelog at site/changelog/ — from git history, in the voice of someone who uses the product
argument-hint: "[\"<release name>\"] [\"<date>\"] [\"<version badge>\"]"
metadata:
internal: "true"
---
Turns what shipped since the last published release into one human-readable entry
on `site/changelog/index.html`, plus the RSS item, the structured data, and the
sitemap.
## Usage
```
/add-changelog-entry # everything since the newest published entry
/add-changelog-entry "Bring your own models" "Sep 2 2026" "Desktop 0.4.0"
```
All three arguments are optional:
- **release name** — omit it and you write one (see *Naming the release*).
- **date** — defaults to today, format `Mon D YYYY`.
- **version badge** — only pass one if that version was actually **released**.
See *Where versions come from* below; an invented version number is worse
than no badge.
## Where versions come from
`CHANGELOG.md` at the repo root is the engineering record — Keep a Changelog
format, versioned against the desktop shell (`desktop/src-tauri/tauri.conf.json`),
and read by `.github/scripts/release-notes.mjs` when a release is cut. This page
is its human rendering, aimed at someone deciding whether to install rather than
someone reading a diff. **They must not disagree about what shipped.**
A version badge is only truthful when three things line up:
```bash
gh release list # the release exists
git ls-remote --tags origin # the tag exists
grep -n '^## \[' CHANGELOG.md # the section is dated, not "unreleased"
```
A bump in `tauri.conf.json` is not a release — 0.3.0 was bumped in-tree and no
one could ever install it, so it carries no badge here. Badge the newest entry
with the version a reader can install today and leave the older entries bare;
they are inside that release too, and repeating it down the page implies
releases that never happened.
When the badge is real, link it to its release:
```html
<a class="cl-version" href="https://github.com/5hirish/duct/releases/tag/desktop-vX.Y.Z" rel="noopener">Desktop X.Y.Z</a>
```
---
## Phase 1: Find out what actually shipped
### 1a. Establish the range
The newest `<article class="cl-release" id="YYYY-MM-DD">` in
`site/changelog/index.html` is the last published release. That date is the
lower bound:
```bash
git log --since=<that date> --date=short --pretty='%ad %s%n%b' --no-merges
```
Read the bodies, not just the subjects. This repo's commit messages explain
*why* — that reasoning is usually the sentence a reader wants, one translation
away.
### 1b. Cut everything that is not user-visible
Delete from the candidate list:
- refactors, renames, test changes, CI and build plumbing, dependency bumps
- documentation, agent instruction files, repo hygiene
- work behind a flag that is still off, or a migration nobody will notice
- fixes to bugs that were never released — nobody experienced them
A dependency bump earns a line only when it closed a vulnerability that affected
users, and then the line is about the fix, not the version number.
### 1c. Verify each survivor
Every bullet you write must trace to a commit in the range. **Never write a line
because it would round out a section.** If a group has one bullet, ship one
bullet. If a release has nothing user-visible in it, say so and stop — a skipped
week is honest; a padded entry teaches readers to stop reading.
---
## Phase 2: Write it
### Naming the release
2–5 words, sentence case, concrete, no version numbers. It names the *theme* of
the release, and it is the `<h2>` — so it is also the thing search engines and
AI answers quote.
- Good: `Bring your own models` · `Duct starts remembering` · `From insight to execution`
- Bad: `August update` · `Improvements and bug fixes` · `v0.4.0`
If the release has no theme — three unrelated fixes — name the largest one and
let the rest sit under their groups.
### The lede
One or two sentences under the title, `<p class="cl-lede">`. State what changed
for the reader, not what was built. It is the RSS description and the social
preview, so it has to stand alone.
### Groups
Use these labels, in this order, skipping any that do not apply:
`Models & agents` · `Insights` · `Memory` · `Connectors` · `Execution` ·
`Workspace` · `Desktop` · `Reliability` · `Security`
At most 4 groups and 5 bullets per group. Past that, you are shipping a diff,
not a changelog — cut the weakest lines.
### Bullet voice
Each bullet is **a bold lead phrase naming the change**, then the detail in
plain prose. Same voice as the blog: direct, specific, no filler.
- `<strong>Three tiers, one job map.</strong> Choose a Heavy, Standard and Light model in settings. Every agent job picks the tier it needs, so you are not selecting a model feature by feature.`
- Not: `Added support for configurable model tier mapping in the agents module (#123).`
Rules:
- No commit hashes, PR numbers, file paths, module names, or internal jargon.
- Name real third-party tools — `Mixpanel`, `Google Ads`, `Microsoft Clarity`.
Those are the terms people search for, and the reason this page ranks.
- A fix says what now works, not what was broken in the abstract: *"Connecting
through the browser reports success as success"* beats *"fixed OAuth relay
state bug"*.
- Do not promise anything not in the release. No roadmap, no "coming soon".
---
## Phase 3: Publish it
Five files, every time. A missed one is invisible until it is embarrassing.
### 3a. `site/changelog/index.html` — the entry
Insert as the **first** `<article>` inside `.cl-wrap`, above the previous newest:
```html
<!-- RELEASE: YYYY-MM-DD -->
<article class="cl-release" id="YYYY-MM-DD" aria-labelledby="r-YYYY-MM-DD">
<div class="cl-rail">
<span class="cl-date">Mon D, YYYY</span>
<span class="cl-version">Desktop 0.4.0</span>
<a class="cl-permalink" href="#YYYY-MM-DD" aria-label="Permalink to the Month D, YYYY release"># permalink</a>
</div>
<div class="cl-body">
<h2 class="cl-title" id="r-YYYY-MM-DD">Release name</h2>
<p class="cl-lede">One or two sentences.</p>
<div class="cl-group">
<p class="cl-group-label">Group label</p>
<ul class="cl-list">
<li><strong>Lead phrase.</strong> The detail.</li>
</ul>
</div>
</div>
</article>
```
- The `id` is the ISO date and is permanent — it is the shareable link. Never
renumber or reuse one.
- Drop the version line entirely when no version was released — most entries
have none. When one was, it is the `<a class="cl-version">` form above.
- Escape `&` as `&` and use `’` / `“` / `”` for quotes and
apostrophes, matching the existing entries.
- The year strip is a `<div role="navigation">`, not a `<nav>` — the bare `nav`
rule in `duct.css` is the fixed site header and will hijack a second one.
### 3b. `site/changelog/index.html` — the structured data
In the `application/ld+json` block:
- Prepend a `ListItem` to `mainEntity.itemListElement` with the new release name
and `https://getduct.ai/changelog/#YYYY-MM-DD`, then renumber `position` on
every item (1 = newest).
- Update `about.softwareVersion` when a version shipped.
### 3c. `site/changelog/feed.xml`
Prepend an `<item>` above the current newest and update `<lastBuildDate>`:
```xml
<item>
<title>Release name</title>
<link>https://getduct.ai/changelog/#YYYY-MM-DD</link>
<guid isPermaLink="false">duct-changelog-YYYY-MM-DD</guid>
<pubDate>Day, DD Mon YYYY 09:00:00 GMT</pubDate>
<description>The lede, expanded to 2–3 sentences. Plain text, no markup.</description>
</item>
```
`pubDate` is RFC 822 (`Wed, 02 Sep 2026 09:00:00 GMT`) — a feed reader will
reject anything else. Validate with `xmllint --noout site/changelog/feed.xml`.
### 3d. `site/sitemap.xml`
Update `<lastmod>` on the `https://getduct.ai/changelog/` entry to the release
date in `YYYY-MM-DD`. The entry already exists — do not add a second one, and do
not give release anchors their own URLs.
### 3e. `site/llms.txt`
Only when the shape of the page changes — a new archive year, a new feed. The
per-release lines do not belong there.
Nothing here is generated: `scripts/build_blog.py` renders posts, not releases,
so there is no `--check` to run and no build output to commit.
---
### After the merge: the announcement posts itself
The feed item is also the GitHub Discussion. On every push to `main` that
changes `site/changelog/feed.xml`, `.github/workflows/announce.yml` posts each
new item to Discussions → Announcements: its title, its `<description>`, a link
to the entry, and one line inviting replies. So the feed `<description>` is
read by two audiences, the RSS reader and everyone watching the repository;
write it as a paragraph that stands on its own, never "see below". Do not post
the announcement by hand: the workflow skips an entry already announced, but a
hand-made post has no marker, so the workflow would post it a second time. An
entry that merged before the workflow existed is announced with *Run workflow*
on `announce`, naming its guid.
## Year rollover (the older-releases archive)
In January, last year's entries move off the index so it stays about the current
year:
1. Copy `site/changelog/index.html` to `site/changelog/<lastyear>.html`.
2. In the archive copy: keep only that year's `<article>` blocks; set
`<title>` and `<h1>` to name the year (`Duct changelog — 2026`); set the
canonical and `og:url` to `https://getduct.ai/changelog/2026`; mark that
year's chip `aria-current="page"` and drop `aria-current` from the index
chip; rebuild the `ItemList` from the entries that remain on that page.
3. Remove those `<article>` blocks from `index.html` and add
`<a class="cl-year" href="/changelog/2026">2026</a>` to the year strip on
**both** pages, newest year first.
4. Add the archive URL to `site/sitemap.xml` (`priority` 0.5, `changefreq`
yearly) and to the `## Core pages` list in `site/llms.txt`.
5. Leave the feed alone — it carries recent items, not history.
Every entry keeps its `#YYYY-MM-DD` anchor, so an old link still resolves once
the reader lands on the archive page.
If a single year ever grows past ~40 releases and the page starts to feel like a
scroll test, split it in half (`/changelog/2027-h1`) and add the half to the
strip. Do not paginate — one long page is what earns the links.
---
## Verify before you call it done
```bash
python3 .github/scripts/check-pages.py # what CI runs over the page itself
python3 scripts/check_changelog_sync.py # this page against CHANGELOG.md
cd site && python3 dev_server.py --port 8090
```
`check_changelog_sync.py` is the reason this entry cannot be forgotten: it fails
when the newest dated version in `CHANGELOG.md` is not the newest badge on this
page, or when the newest entry has no feed item. It runs in `make check-site`
and in `site.yml`, and the release workflow runs it against the version being
released before anything builds.
- [ ] `check-pages.py` passes — canonical without `.html`, JSON-LD parses, OG
and Twitter tags complete
- [ ] `/changelog/` renders and the new entry is first
- [ ] The permalink `#YYYY-MM-DD` scrolls to the entry, clear of the fixed nav
- [ ] `/changelog/feed.xml` parses and the new item is on top
- [ ] The JSON-LD block still parses and its positions run 1..N
- [ ] No `.html` in any link you added — this site uses clean URLs, and a smoke
test asserts it
- [ ] Every bullet traces to a commit in the range
- [ ] Any version badge names a released version, and links to its release
- [ ] Nothing internal leaked: no hashes, PR numbers, file paths, module names
- [ ] Mobile at 390px: date and version chip sit on one row above the title