Back to Details

changelog

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

nurb changelog

nurb 更新日志

One surface: 
site/changelog.html
, the static page behind nurb.dev/changelog. One 
<article class="release">
per released version, newest first. There is no build step and no data file; the HTML is the data.
Releases are the unit. A nurb release is a version bump merged to main; the publish workflow tags it and creates a GitHub release whose generated notes list the merged PRs. The changelog entry for a version is written from those PRs, filtered hard.
一个页面：
site/changelog.html
，即nurb.dev/changelog对应的静态页面。每个发布版本对应一个
<article class="release">
元素，按版本从新到旧排列。这里没有构建步骤和数据文件；HTML本身就是数据。
版本是基本单位。nurb的版本发布指的是将版本号更新的PR合并到main分支；发布工作流会为其打上标签并创建GitHub Release，自动生成的发布说明会列出所有已合并的PR。某个版本的更新日志条目就是基于这些PR编写的，且会严格筛选内容。

Step 1: Find the gap

步骤1：找出遗漏的版本

The newest 
id="vX.Y.Z"
in 
site/changelog.html
is the high-water mark.
bash
grep -m1 'id="v' site/changelog.html
gh release list --limit 20
Every tagged release newer than the high-water mark needs an entry. If the user describes a feature in free text instead, write that one entry into the version it shipped in (or the pending version if it hasn't shipped yet) and skip the sweep.
When /release invokes this before the bump PR merges, the newest version has no tag or GitHub release yet. Write its entry anyway: source it from the PRs merged since the last release (
gh pr list --state merged --base main --json title,number,mergedAt
) plus whatever the release branch itself ships, date it today, and keep the tag link, which goes live when the release publishes. The entry lands as part of the release PR, so commit it there instead of leaving it uncommitted.
For each missing version:
bash
gh release view vX.Y.Z --json publishedAt,body
The body lists the PRs. Read a PR (
gh pr view N
) whenever its title alone doesn't tell you what a user would notice.
site/changelog.html
中最新的
id="vX.Y.Z"
是当前已记录的最高版本。
bash
grep -m1 'id="v' site/changelog.html
gh release list --limit 20
所有比最高版本新的带标签版本都需要编写条目。如果用户用自由文本描述了某个功能，则将该条目写入其所属的已发布版本（若尚未发布则写入待发布版本），无需遍历所有版本。
当/release在版本更新PR合并前调用此流程时，最新版本还没有标签或GitHub Release。即便如此也要编写条目：基于自上次发布以来合并的PR（
gh pr list --state merged --base main --json title,number,mergedAt
）加上版本分支本身包含的内容，日期设为当天，保留标签链接（发布后链接会自动生效）。该条目作为版本更新PR的一部分提交，而非保留为未提交状态。
对于每个遗漏的版本：
bash
gh release view vX.Y.Z --json publishedAt,body
发布说明的正文会列出PR。如果仅看PR标题无法判断用户是否会注意到相关变化，就查看PR详情（
gh pr view N
）。

Step 2: Filter to what earns a line

步骤2：筛选值得写入的内容

Most PRs are not changelog lines. A PR earns one only if someone using nurb could notice the difference without reading the code.
Yes: a new capability in the viewer or the modeling vocabulary, a new check, a behavior change they'd feel, a fix for something that visibly broke, a change to how their AI works with them (asks for measurements, names sliders in their words).
No: CI, tests, refactors, repo docs, CLAUDE.md, release plumbing, skill-file mechanics with no visible effect, marketing site tweaks.
Group by capability, not by PR. Several PRs polishing one feature collapse into one line. A version whose every PR is internal gets no entry at all; say so in the report rather than padding.
大多数PR无需写入更新日志。只有当使用nurb的用户无需查看代码就能察觉到变化时，该PR才值得写入一条日志。
符合条件的情况：查看器或建模词汇新增功能、新增检查项、用户能感知到的行为变化、修复可见的故障、AI交互方式的变化（如要求测量数据、用用户的语言命名滑块）。
不符合条件的情况：CI配置、测试、重构、仓库文档、CLAUDE.md、发布流程相关修改、无可见效果的技能文件机制调整、营销网站微调。
按功能分组，而非按PR分组。多个优化同一功能的PR合并为一条日志。如果某个版本的所有PR都是内部修改，则无需编写条目；在报告中说明即可，不要凑数。

Step 3: Draft the copy

步骤3：撰写文案

The audience is a hobbyist with a printer, not a programmer. They talk to their AI and judge parts in a browser.
  • Never mention Python, module names, function names, build123d, OCCT, or agent-harness jargon. 
    stand()
    is "diagonal printing"; 
    nurb inspect
    is "your AI can inspect a part".
  • "Your AI" is the actor for agent-side changes, matching the landing page.
  • Sentence case, second person, plain English. Say what changed and what they can now do, then stop. No rationale, no design defense.
  • No em-dashes, no exclamation points, no emoji, no marketing fluff.
  • Each line gets a tag: 
    new
    , 
    improved
    , or 
    fixed
    . Only 
    new
    also carries the class (
    <b class="tag new">
    ); the other two are 
    <b class="tag">improved</b>
    and 
    <b class="tag">fixed</b>
    .
  • A headline capability may lead its line with a bold two-or-three-word name: 
    <b>Assemblies.</b>
    .
受众是拥有3D打印机的爱好者，而非程序员。他们会与AI对话，并在浏览器中评估模型。
  • 绝不要提及Python、模块名、函数名、build123d、OCCT或agent-harness这类术语。
    stand()
    译为「倾斜打印」；
    nurb inspect
    译为「你的AI可以检查模型」。
  • 涉及Agent端的变化时，以「你的AI」作为主语，与首页风格保持一致。
  • 使用句首大写、第二人称、通俗易懂的中文。说明变化内容以及用户现在可以做什么，点到为止。无需解释理由或辩护设计。
  • 不要使用破折号、感叹号、表情符号或营销话术。
  • 每条日志都要加上标签：
    new
    、
    improved
    或
    fixed
    。只有
    new
    标签需要添加类名（
    <b class="tag new">
    ）；另外两个标签的格式为
    <b class="tag">improved</b>
    和
    <b class="tag">fixed</b>
    。
  • 重要功能可以在条目前加上两到三个词的加粗名称：
    <b>装配功能。</b>
    。

Step 4: Write the page

步骤4：写入页面

Insert the new 
<article class="release" id="vX.Y.Z">
at the top of 
<main>
, right after the 
.lede
paragraph. Copy the markup shape of the entry below it exactly:
html
<article class="release" id="v0.9.0">
  <div class="meta"><span class="ver"><a href="https://github.com/Shpigford/nurb/releases/tag/v0.9.0">v0.9.0</a></span><time datetime="2026-07-31">July 31, 2026</time></div>
  <ul>
    <li><b class="tag new">new</b><span><b>Diagonal printing.</b> A part that prints better tilted...</span></li>
    <li><b class="tag">fixed</b><span>...</span></li>
  </ul>
</article>
The date is the release's 
publishedAt
date, not today (a pre-merge entry uses today, which becomes the publish date when the PR merges). Never reword or delete an already-published entry; its 
id
is a live anchor.
将新的
<article class="release" id="vX.Y.Z">
插入到
<main>
标签的顶部，紧跟在
.lede
段落之后。完全复制下方已有条目的标记格式：
html
<article class="release" id="v0.9.0">
  <div class="meta"><span class="ver"><a href="https://github.com/Shpigford/nurb/releases/tag/v0.9.0">v0.9.0</a></span><time datetime="2026-07-31">July 31, 2026</time></div>
  <ul>
    <li><b class="tag new">new</b><span><b>Diagonal printing.</b> A part that prints better tilted...</span></li>
    <li><b class="tag">fixed</b><span>...</span></li>
  </ul>
</article>
日期使用版本的
publishedAt
日期，而非当天（预合并条目使用当天日期，PR合并后会自动变为发布日期）。绝不要修改或删除已发布的条目；其
id
是有效的锚点链接。

Step 5: Verify

步骤5：验证

Look at the page, don't just lint it: serve 
site/
(
python3 -m http.server 7878 -d site
), open 
http://localhost:7878/changelog.html
with whatever browser tooling is available, and screenshot it. Check the new entry renders like its neighbors, then kill the server. Also, silence is pass on both of these:
bash
git diff -U0 site/changelog.html | grep '^+.*—'   # em-dashes in what you added
grep -o 'id="v[0-9.]*"' site/changelog.html | uniq -d  # duplicate versions
And confirm by eye that versions still descend down the page.
查看页面效果，不要仅依赖代码检查：启动
site/
目录的服务（
python3 -m http.server 7878 -d site
），用可用的浏览器打开
http://localhost:7878/changelog.html
并截图。检查新条目与已有条目的渲染效果一致，然后关闭服务。同时，确保以下两个命令没有输出内容：
bash
git diff -U0 site/changelog.html | grep '^+.*—'   # 检查新增内容中是否有破折号
grep -o 'id="v[0-9.]*"' site/changelog.html | uniq -d  # 检查是否有重复的版本号
还要目视确认版本号仍按从新到旧的顺序排列。

Step 6: Report

步骤6：报告

List each version with its lines and tags, plus one line for what was skipped and why. Leave the change uncommitted unless asked.
列出每个版本的日志条目及标签，再用一行说明被跳过的内容及原因。除非被要求，否则不要提交更改。