Skip to main content
Version: Next

Changelog entry conventions

This page explains where each entry in the changelog comes from, what it looks like, and who maintains it. Yearly files such as 2026.md are generated end to end; this page is the only manual entry point.

Recording scope​

RecordedNot recorded
Documents added / revised / removed on the main branchDrafts, branches in progress, unmerged work
Corrections and breaking changes declared in the commit subjectPure styling, configuration or build-script tweaks
The files touched, tags, and target code versionWord-level diffs (that is git log's job; here we only state conclusions)

Why drafts are excluded: a changelog exists for subscribers and for people checking history later, and only merged content can be "what we stand by". Listing work in progress invites readers to code against unfinished conclusions.

Entry structure​

## 2026-11-13

### Added · Site Guide

- Files: [Site Guide](/en/)
- Version: 5.8 | Tags: Guide
- Compare: [8cc4a77](https://github.com/<owner>/<repo>/commit/8cc4a77)

Four layers, each doing one job:

  1. Date H2 — entries grouped by commit date, newest first.
  2. Entry H3 — category · document title. The heading text is the anchor, so every entry can be shared on its own.
  3. Three metadata lines — files (jump to current content), version and tags (decide whether this applies to your build), compare (jump to the real diff).
  4. Category — decides whether you need to read it; rules below.

How categories are decided​

A machine can tell whether a file was added or modified; it cannot tell whether that modification corrected an earlier wrong conclusion. Hence two sources:

CategorySourceRule
Addedgit statusfile appeared (A)
Revisedgit statusfile content changed (M / R)
Breaking changecommit subject prefixfile deleted (D), or the subject starts with [破坏性更正]
Correctioncommit subject prefixthe subject starts with [勘误]

Prefixes are compared verbatim against changelog.kinds in site.config.js, so changing the configured word changes the prefix. Entry titles come from the document title, not the commit subject, so prefixes never leak into the body.

Examples:

[勘误] 修正 StreamableManager 回调线程归属的结论
[破坏性更正] 可见性标记的口径改为按视图索引

How generation works​

npm run changelog # regenerate every yearly file (Chinese and English)
npm run changelog:check # check only: exit code 1 if a commit is unrecorded (CI)
npm run changelog -- --dry-run # print what would be written, touch nothing
npm run changelog -- --since=2026-01-01 # only replay commits after a given date

Three hard rules:

  1. Never hand-edit yearly files. The generator rewrites frontmatter and body wholesale; manual edits vanish on the next run.
  2. New years open automatically. The first commit after New Year creates 2027.md; sidebar_position is derived from the year, no configuration needed.
  3. Compare links are conditional. When repo.owner / repo.name in site.config.js are empty, no compare link is emitted at all — better absent than broken. Fill them in and regenerate.

Relationship to the newsletter​

The changelog is the only input for the digest: the subscriber script reads the entries dated today from the yearly file and groups them by tags. The three metadata lines are not decoration — an entry missing files or tags degrades to a bare title in the digest, and its value drops sharply. Write the category and title so a reader understands the entry at a glance.

Relationship to versioning​

Historical versions such as 5.8 are snapshots and do not change with edits on the main branch; the changelog only records the main branch. When the two disagree, check which version of the page you are reading first, then the version field of the entry.