openseo-release-notes

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

OpenSEO release notes

OpenSEO 发布说明

Cut a release for this repo end to end. The deliverables are a version bump in

package.json

, a new

release-notes/v<version>.md

, and a PR against

origin/main

titled

release: v<version>

完成此仓库的端到端版本发布。交付成果包括：

package.json

中的版本号升级、新的

release-notes/v<version>.md

发布说明文件，以及针对

origin/main

分支、标题为

release: v<version>

的PR。

1. Bump the version

1. 升级版本号

Read
```
package.json
```
. If the branch has already bumped
```
version
```
, treat that as the source of truth and do not change it.
Otherwise bump the patch version (e.g.
```
0.0.19
```
→
```
0.0.20
```
). Only bump minor/major if explicitly asked.

读取
```
package.json
```
。如果分支已经升级了
```
version
```
字段，则以此为准，无需修改。
否则升级补丁版本（例如
```
0.0.19
```
→
```
0.0.20
```
）。仅在明确要求时才升级次要/主要版本。

2. Collect the changes since the last release

2. 收集上次发布以来的变更

Find the latest tag:

git tag --sort=-creatordate | head -1

. Verify the branch is up to date with

origin/main

(

git fetch origin main && git log HEAD..origin/main --oneline

should be empty; flag it if not).

List commits:
```
git log <last-tag>..HEAD --oneline
```
. You can also run
```
pnpm release:notes
```
for a raw commit inventory — use it only as a checklist of candidate changes, never as the draft's structure (its Improved/Changed/Docs sections must not appear in the notes).
For each commit, fetch the PR body and author (
```
gh pr view <num> --repo <repo> --json title,body,author
```
) — squash-commit subjects can be stale. The
```
(#NN)
```
in commit subjects can reference either repo: try
```
bensenescu/open-seo
```
(origin) first and fall back to
```
every-app/open-seo
```
(public) — outside contributors' PRs and their handles live on the public repo. Commits with no
```
(#NN)
```
may still be an outside contribution with a public PR (
```
gh pr list --repo every-app/open-seo --state merged --author <login>
```
); check
```
git log --format=%an
```
for the author. Verify claims against the final code when a PR body and commit subject disagree (features get reverted before merge).
Record the PR author's GitHub handle alongside each change so the bullet can credit them.

查找最新标签：
```
git tag --sort=-creatordate | head -1
```
。验证分支是否与
```
origin/main
```
同步（
```
git fetch origin main && git log HEAD..origin/main --oneline
```
应返回空内容；若不为空则标记此问题）。
列出提交记录：
```
git log <last-tag>..HEAD --oneline
```
。你也可以运行
```
pnpm release:notes
```
获取原始提交清单——仅将其作为候选变更的检查清单，绝不能直接用作发布说明的结构（其Improved/Changed/Docs部分不得出现在最终说明中）。
针对每个提交，获取对应的PR正文和作者信息（
```
gh pr view <num> --repo <repo> --json title,body,author
```
）—— squash提交的主题可能已过时。提交主题中的
```
(#NN)
```
可能指向任意一个仓库：优先尝试
```
bensenescu/open-seo
```
（源仓库），若失败则 fallback 到
```
every-app/open-seo
```
（公开仓库）——外部贡献者的PR及其账号信息存储在公开仓库中。没有
```
(#NN)
```
标记的提交仍可能是带有公开PR的外部贡献（
```
gh pr list --repo every-app/open-seo --state merged --author <login>
```
）；可通过
```
git log --format=%an
```
查看作者信息。当PR正文与提交主题不一致时，需对照最终代码验证相关描述（功能可能在合并前被回退）。
记录每个变更对应的PR作者GitHub账号，以便在项目符号中署名致谢。

3. Draft the notes

3. 撰写发布说明

Write

release-notes/v<version>.md

. release-notes/v0.0.24.md
is the canonical style exemplar — match it (v0.0.25 and later follow the same style); v0.0.23 and earlier are the old verbose style, never imitate them. The notes are a scannable digest, not documentation: the whole file fits on one screen (roughly 15 lines including headings), and every line earns its place.

Format:

Top line: a fragment naming the release's 2–3 highlights ("GSC UI, improved app layout and beta in app agent."). Not a "This release brings…" sentence.
Sections:
```
## What's new
```
and
```
## Fixed
```
only. There is no "Improved" section — an improvement is either headline-worthy (What's new) or it's cut.
What's new bullets name the feature; they don't sell it. One short line each ("Redesigned the app layout", "Get GSC Insights inside the app") — no em-dash feature tours, no "so you can…" benefit copy, no lists of everything the feature touches. If the name alone is ambiguous, one clause of plain-words context is the maximum.
At most one sub-bullet per feature, one short line: the single most useful detail, a requirement ("Requires
```
OPENROUTER_API_KEY
```
"), or an expectation-setter.
Label rough features "(Beta)" and set expectations honestly, including pointing at the better alternative for now. The expectation-setter rides the top-level line after a dash ("(Beta) In app agent - MCP is still recommended, but we'll be working to improve this during the summer."), keeping the sub-bullet slot free for a requirement or detail.
Fixed: 3–5 bullets, one plain sentence each, only bugs a user plausibly hit and would recognize ("Claude answers in AI search work again."). No error codes, status codes, schema/infra vocabulary, or mechanism. If more than four qualify, keep the ones hit in core flows (searches, audits, tracking, MCP answers) and drop fixes for recovering self-inflicted state (re-adding, un-archiving, refreshing) first.
Credit the contributor. End the bullet with
```
— thanks @handle
```
for outside contributors only — never for the maintainer's own PRs (
```
bensenescu
```
). Credit goes on the top-level bullet, not sub-bullets. Multiple contributors:
```
— thanks @a, @b
```
.

End with:

Full Changelog: https://github.com/every-app/open-seo/compare/v<prev>...v<version>

Curation — this is where the work is. Cut aggressively; the Full Changelog link covers the long tail:

Only changes to the product itself — the app, the MCP tools, the SEO data/features someone running OpenSEO actually uses. Litmus test per bullet: would a self-hoster notice this while using the product? Caring in the abstract (a new backend option, a raised cap) is not enough.
Do NOT mention:
- Marketing-website (
  web/
  ) changes — landing pages, copy, positioning, blog.
- Pricing / plans / subscription / billing — paywalls, free-trial/plan changes, Autumn config. Hosted-commercial concerns, irrelevant to self-hosters.
- Onboarding-flow-only changes — signup/onboarding chat, profiling steps, upgrade rails, email-verification UX. Not a product capability, even when sizable.
- Hosted-app internals & meta — analytics, specs/ADRs, CI, refactors, dependency bumps.
- Invisible-to-the-user work, even when product-relevant — security hardening, raised caps/limits, stability/memory/perf fixes, database/backend options and migrations. A user reading the notes should recognize every line from using the product; if they'd only notice it in a config file or an incident that no longer happens, cut it.
When torn between including and cutting, cut. A 4-bullet What's new that gets read beats a 10-bullet one that doesn't.
Never invent features — every claim must trace to a commit.
Numbers in bullets are usually selling — cut them; if one is genuinely load-bearing, quote the conservative, typical figure, never a cherry-picked best case.

编写

release-notes/v<version>.md

文件。release-notes/v0.0.24.md
是规范风格示例——需与其保持一致（v0.0.25及后续版本遵循相同风格）；v0.0.23及更早版本为旧的冗长风格，请勿模仿。发布说明是便于快速浏览的摘要，而非文档：整个文件应能在一个屏幕内显示（包括标题在内约15行），每一行都要有存在的价值。

格式要求：

首行：用短语列出此版本的2-3个亮点（例如"GSC UI、改进的应用布局及应用内Agent测试版"）。不要使用"此版本带来…"这类完整句子。
章节：仅保留
```
## What's new
```
和
```
## Fixed
```
。没有"Improved"章节——改进内容要么值得作为亮点（归入What's new），要么就删除。
What's new的项目符号仅命名功能，不做宣传。每个项目符号为简短一行（例如"重新设计应用布局"、"在应用内获取GSC洞察"）——不要使用破折号展开功能介绍，不要添加"让你可以…"这类收益描述，不要列出功能涉及的所有内容。如果仅靠名称无法明确含义，最多添加一句平实的上下文说明。
每个功能最多一个子项目符号，且为简短一行：包含最有用的细节、要求（例如"需要
```
OPENROUTER_API_KEY
```
"）或预期说明。
将未成熟的功能标记为"(Beta)"，并如实说明预期，包括指出当前更优的替代方案。预期说明需放在顶层项目符号的末尾，用破折号分隔（例如"(Beta) 应用内Agent - 目前仍推荐使用MCP，但我们将在夏季持续改进此功能"），为子项目符号预留空间以放置要求或细节。
Fixed部分：3-5个项目符号，每个为平实的句子，仅包含用户可能遇到并能识别的问题（例如"AI搜索中的Claude回复功能恢复正常"）。不要提及错误码、状态码、架构/基础设施术语或技术机制。如果符合条件的条目超过4个，保留核心流程（搜索、审核、跟踪、MCP回复）中的修复内容，优先删除针对自恢复状态（重新添加、取消归档、刷新）的修复。
致谢贡献者。仅对外部贡献者在项目符号末尾添加
```
— thanks @handle
```
——维护者（
```
bensenescu
```
）自己的PR无需致谢。致谢信息放在顶层项目符号中，而非子项目符号。多个贡献者格式：
```
— thanks @a, @b
```
。

末尾添加：

Full Changelog: https://github.com/every-app/open-seo/compare/v<prev>...v<version>

内容筛选——这是核心工作。要严格筛选；完整变更日志链接会涵盖所有次要内容：

仅保留产品本身的变更——即应用、MCP工具、使用OpenSEO的用户实际会用到的SEO数据/功能。每个项目符号的检验标准：自托管用户在使用产品时会注意到这个变更吗？ 抽象层面的改进（如新的后端选项、上限提升）不足以入选。
请勿提及：
- 营销网站(
  web/
  )变更——着陆页、文案、定位、博客。
- 定价/套餐/订阅/计费——付费墙、免费试用/套餐变更、Autumn配置。这些是托管版商业相关内容，与自托管用户无关。
- 仅涉及入职流程的变更——注册/入职聊天、配置步骤、升级引导、邮箱验证UX。这不属于产品功能，即使改动很大也不列入。
- 托管版应用内部及元数据——分析、规格/ADR、CI、重构、依赖升级。
- 对用户不可见的工作，即使与产品相关——安全加固、上限提升、稳定性/内存/性能优化、数据库/后端选项及迁移。用户阅读发布说明时应能从产品使用中识别每一条内容；如果只能在配置文件中或已解决的事件中发现，就删除它。
当纠结是否保留时，选择删除。一个4条项目符号的What's new会被用户完整阅读，胜过一个10条项目符号却无人浏览的版本。
绝不能虚构功能——每一项描述都必须能追溯到提交记录。
项目符号中的数字通常是宣传性内容——删除它们；如果某个数字确实必不可少，引用保守的典型数值，绝不要用挑选出的最佳案例。

4. Review and verify

4. 审核与验证

Spawn a reviewer subagent with: the draft, the guidelines above, the per-commit facts you gathered, and repo access. It returns numbered review comments citing which guideline each violates. Its charge includes verbosity: flag any bullet that sells instead of names, any second sub-bullet, any Fixed bullet with mechanism vocabulary, and anything that pushes the file past one screen.
For each substantive comment, spawn a verification subagent (in parallel) that adversarially checks the comment against the actual commits/code and verdicts APPLY / APPLY-MODIFIED / REJECT.
Apply only verified comments.

启动审核子代理，提供以下内容：撰写好的发布说明草稿、上述指南、收集到的每个提交的事实信息，以及仓库访问权限。子代理会返回带编号的审核意见，并指出每条意见违反了哪项指南。其职责还包括检查冗长性：标记任何宣传而非命名功能的项目符号、第二个子项目符号、包含技术机制术语的Fixed项目符号，以及任何导致文件超过一屏长度的内容。
针对每条实质性意见，并行启动验证子代理，对抗性地检查意见与实际提交/代码是否相符，并给出APPLY / APPLY-MODIFIED / REJECT的 verdict。
仅应用经过验证的意见。

5. Open the PR

5. 创建PR

Commit the version bump, release notes, and any skill changes on a branch named
```
claude/v<version>
```
(use the current branch if it already follows this pattern).
Push to
```
origin
```
and open a PR against
```
main
```
titled exactly
```
release: v<version>
```
. PR body: the release notes content.
Do not tag or publish the GitHub release — that happens after merge. After merge, run
```
pnpm release:publish
```
. It reads the version from
```
package.json
```
and publishes the matching
```
release-notes/v<version>.md
```
to
```
every-app/open-seo
```
.

The equivalent command is:

gh release create v<version> \
  --repo every-app/open-seo \
  --title v<version> \
  --notes-file release-notes/v<version>.md

将版本号升级、发布说明及任何skill变更提交到名为
```
claude/v<version>
```
的分支（如果当前分支已符合此命名规则，则直接使用当前分支）。
推送到
```
origin
```
并打开针对
```
main
```
分支的PR，标题必须为
```
release: v<version>
```
。PR正文为发布说明内容。
不要标记或发布GitHub版本——这一步在合并后进行。合并后，运行
```
pnpm release:publish
```
。该命令会从
```
package.json
```
读取版本号，并将对应的
```
release-notes/v<version>.md
```
发布到
```
every-app/open-seo
```
。

等效命令如下：

gh release create v<version> \
  --repo every-app/open-seo \
  --title v<version> \
  --notes-file release-notes/v<version>.md