Skip to content

Commit 7a7ae8a

Browse files
huangruitenghuangruiteng
authored
docs(release): add upgrade decision template (#2852)
1 parent 1180f66 commit 7a7ae8a

7 files changed

Lines changed: 389 additions & 61 deletions

File tree

‎docs/product/README.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,9 @@ contracts.
1313
runtime map for state, interactions, and bounded contexts.
1414
- [Release readiness](release-readiness.md): the currently supported v0.x
1515
install and compatibility boundary.
16+
- [Release note template](release-note-template.md): the copy-ready release
17+
decision summary, product groups, optional-capability guidance, validation,
18+
and bilingual attribution format.
1619
- [Public adoption loop](public-adoption-loop.md): a public-safe path from
1720
external attempt to inspectable feedback.
1821
- [Domain capability packs](domain-capability-packs.md): what belongs in the

‎docs/product/foundations/beginner-loop-presets.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -52,7 +52,7 @@ badges or change project state.
5252
| Pattern | User value | LoopX default | Recommendation |
5353
| --- | --- | --- | --- |
5454
| Daily triage | Gives a repo owner a regular project digest without asking them to read every issue, PR, or status file. | L1 report-only. Read status, active todos, open gates, stale signals, and next actions. No code edits. | Absorb now as the first beginner preset. It demonstrates LoopX state, scheduler, quota, and no-surprise writeback with low risk. |
55-
| Changelog draft | Turns recent merged work into a release-note draft and gives maintainers something immediately useful. | L1 draft-only. Produce a human-reviewed release note draft with PR links when available. No publish action. | Absorb now as a low-risk showcase preset. It is easy to demo and helps README readers understand concrete output. |
55+
| Changelog draft | Turns recent merged work into a release-note draft and gives maintainers something immediately useful. | L1 draft-only. Answer who should upgrade, what the release solves, whether it is breaking, how to verify it, and who contributed; then preserve PR-backed product groups and optional-capability lifecycle guidance. No publish action. | Absorb now as a low-risk showcase preset. It is easy to demo and helps README readers understand concrete output. |
5656
| PR watch | Keeps a PR from stalling by watching review, CI, and merge blockers. | L1 watch by default; L2 only after explicit opt-in. No auto-merge. | Absorb as an early preset, but present it as review assistance, not autonomous merging. |
5757
| Issue triage | Converts noisy issue queues into priority, labels, and next-response suggestions. | L1 propose-only. Suggest labels, owners, duplicates, and next replies. No external write unless explicitly approved. | Absorb after Daily Triage because it shares most read-only plumbing and is friendly to public OSS repos. |
5858
| CI sweeper | Fixes obvious broken checks and removes boring maintainer toil. | L2 opt-in. Worktree-only patches, verifier required, cost cap required, human review before merge. | Include as a high-value advanced preset. Do not make it a beginner default, but do not bury it; it is one of the clearest ROI stories once gates are visible. |

‎docs/product/release-note-template.md‎

Lines changed: 175 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,175 @@
1+
<!--
2+
Copy this file into the draft GitHub release body. Replace every angle-bracket
3+
placeholder, remove instructional comments, and omit empty detailed groups.
4+
Keep the Release Decision section compact enough to scan before the fold.
5+
-->
6+
7+
# LoopX vX.Y.Z
8+
9+
<Summarize the release in one outcome-led paragraph. Name the most important
10+
improvement and its authority or compatibility boundary without repeating the
11+
section list.>
12+
13+
## Release Decision
14+
15+
**Who should upgrade:** <Name the affected users or operators and say who can
16+
remain on the current version. Do not write "everyone" without a reason.>
17+
18+
**What this release solves:** <State the concrete failure, missing workflow, or
19+
reliability gap addressed by this release.>
20+
21+
**Breaking changes:** <Start with "No." or "Yes." If yes, give the migration
22+
path. If no, still name any changed default, deprecated path, or experimental
23+
surface that existing users should notice.>
24+
25+
**How to verify:** <State the expected post-upgrade result, then provide the
26+
smallest commands that prove package identity and the affected behavior.>
27+
28+
**Contributors:** <Name the release maintainer and every community contributor
29+
from the tag range, or explicitly state that there were no community
30+
contributions in this release. Link the detailed section when present.>
31+
32+
```bash
33+
loopx --version
34+
loopx doctor
35+
<focused-command-that-proves-the-affected-behavior>
36+
```
37+
38+
<!-- Omit an empty product group. Every material claim needs direct PR links. -->
39+
40+
## State Kernel & Control Plane
41+
42+
- <User-visible state, todo, quota, scheduler, gate, peer-routing, or authority
43+
change with direct PR links.>
44+
45+
## Capabilities & Workflows
46+
47+
- <Shipped user outcome, shipped layer, and any last-mile boundary with direct
48+
PR links.>
49+
50+
## Quality & Testing
51+
52+
- <Durable regression coverage, canary, qualification, or release-gate change
53+
with direct PR links.>
54+
55+
## Benchmarks & Integrations
56+
57+
- <Host, provider, benchmark, or external-boundary change with direct PR links.
58+
State explicitly when no benchmark or long-horizon outcome claim is made.>
59+
60+
## Documentation & Compatibility
61+
62+
- <Documentation, migration, default, deprecation, or compatibility detail with
63+
direct PR links. Repeat the persisted-state migration decision explicitly.>
64+
65+
<!--
66+
Include this section only when the tag range contains eligible contributors
67+
other than @huangruiteng. Keep founder stewardship out of this community-only
68+
section; it is already named in Release Decision when relevant.
69+
-->
70+
71+
## Community Contributors
72+
73+
- <Link each eligible GitHub handle and PR, and name the concrete contribution.
74+
Call out external or first-time contributors when applicable.>
75+
76+
## Optional Capability Activation & Use
77+
78+
No new optional capability activation is introduced in this release.
79+
80+
<!--
81+
If the release adds or materially changes an experimental, default-off, or
82+
opt-in surface, replace the no-change declaration with one entry per surface:
83+
84+
### <Surface Name>
85+
86+
**Activation:** <Exact install, enable, command, or profile opt-in.>
87+
88+
**Validation:** <Minimum runnable readback or verification command.>
89+
90+
**Disable / rollback:** <Exact disable, uninstall, envelope removal, or rollback.>
91+
92+
**Authority boundary:** <Writes, merges, providers, privacy, or host powers not granted.>
93+
94+
**Docs:** https://github.com/huangruiteng/loopx/blob/vX.Y.Z/<canonical-doc>
95+
96+
```bash
97+
<activation-command>
98+
<validation-command>
99+
<disable-or-rollback-command>
100+
```
101+
-->
102+
103+
## Install / Update
104+
105+
New users should install from the named stable ref. Existing users should
106+
preview the update, then execute it explicitly:
107+
108+
```bash
109+
loopx update --check --ref stable
110+
loopx update --execute --ref stable
111+
loopx doctor
112+
```
113+
114+
## 中文摘要
115+
116+
### 升级决策
117+
118+
**谁需要升级：**<写明受影响的用户或 operator，以及谁可以暂不升级。>
119+
120+
**解决了什么：**<用结果语言说明本版本解决的故障、缺口或可靠性问题。>
121+
122+
**是否有破坏性变更：**<以“无。”或“有。”开头；若有则给出迁移路径，
123+
若无也要说明默认值、废弃路径或实验能力的变化。>
124+
125+
**如何验证：**<指向上方最小验证命令，并写明升级后的预期结果。>
126+
127+
**贡献者：**<用 GitHub handle 列出 release maintainer 与 tag range 内的
128+
社区贡献者；若没有社区贡献者则明确说明。>
129+
130+
<!-- 保留与英文相同的非空产品分组、PR 归因和边界，可以更短但不能弱化。 -->
131+
132+
### 状态内核与控制面
133+
134+
- <中文摘要与 PR 链接。>
135+
136+
### 能力与工作流
137+
138+
- <中文摘要与 PR 链接。>
139+
140+
### 质量与测试
141+
142+
- <中文摘要与 PR 链接。>
143+
144+
### 基准与集成
145+
146+
- <中文摘要与 PR 链接。>
147+
148+
### 文档与兼容性
149+
150+
- <中文摘要与 PR 链接。>
151+
152+
<!-- 英文存在 Community Contributors 时，保留同一人员、PR 和贡献范围。 -->
153+
154+
### 社区贡献者
155+
156+
- <社区贡献者中文归因。>
157+
158+
### 可选能力启用与使用
159+
160+
本版本未新增可选能力启用入口。
161+
162+
<!--
163+
若英文存在 optional capability 条目，以 #### <Surface Name> 逐项镜像，并使用：
164+
**启用：**、**验证：**、**停用 / 回退：**、**权限边界：**、**文档：**，
165+
同时保留可运行的 bash 命令块。
166+
-->
167+
168+
### 发布验证
169+
170+
- Package version and public tag: `X.Y.Z` / `vX.Y.Z`.
171+
- Tag target: `<full-commit-sha>`.
172+
- <Exact-commit checks that passed, including failures or skips without
173+
overclaiming hosted, live-model, benchmark, or long-horizon evidence.>
174+
175+
Compare: https://github.com/huangruiteng/loopx/compare/vPREVIOUS...vX.Y.Z

‎docs/product/release-readiness.md‎

Lines changed: 21 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -552,6 +552,25 @@ Treat these as experimental until their contract docs say otherwise:
552552

553553
## Release Note Checklist
554554

555+
Start the final GitHub release body from the canonical
556+
[release note template](release-note-template.md). Its first substantive
557+
section is a compact `## Release Decision` block that answers the five
558+
questions a reader needs before inspecting the detailed changelog:
559+
560+
| Field | Required decision |
561+
| --- | --- |
562+
| `**Who should upgrade:**` | Name the affected users or operators, the reason to upgrade now, and who can remain on the current version. |
563+
| `**What this release solves:**` | State the concrete failure, missing workflow, or reliability gap in user-outcome language. |
564+
| `**Breaking changes:**` | Start with `No.` or `Yes.`; when yes, give the migration path, and when no, still disclose changed defaults, deprecations, or experimental boundaries. |
565+
| `**How to verify:**` | State the expected post-upgrade result and include a minimal runnable `bash` block that proves package identity and the affected behavior. |
566+
| `**Contributors:**` | Name the release maintainer and community contributors from the tag range, or explicitly say that the release has no community contribution. |
567+
568+
Mirror the same decisions under `### 升级决策` in the Chinese summary with
569+
`**谁需要升级：**`, `**解决了什么：**`, `**是否有破坏性变更：**`,
570+
`**如何验证：**`, and `**贡献者：**`. The summary is a decision aid, not a
571+
replacement for the detailed product groups, per-claim PR evidence, optional
572+
capability lifecycle, or exact-commit validation evidence below it.
573+
555574
Keep user-visible product changes first. When merged pull requests between the
556575
previous and current tags include community contributors other than project
557576
founder `@huangruiteng`, add a prominent `## Community Contributors` section
@@ -602,13 +621,11 @@ still useful at the end, but it does not replace per-claim PR attribution.
602621
Avoid bare PR ranges as the only evidence because ranges can hide omitted or
603622
unrelated changes.
604623

605-
Every public release note or update note should also answer:
624+
After the decision summary and product groups, every public release note should
625+
also record:
606626

607-
- What user-visible capability became more dependable?
608627
- What package version and public tag name this stable release uses?
609628
- Which install/update path should a new user follow?
610-
- Which commands, docs, or smokes prove the claim?
611-
- Are there compatibility or migration notes for existing local state?
612629
- Which surfaces are still experimental or intentionally excluded?
613630
- For every new or materially changed experimental, default-off, or opt-in
614631
capability, include an **Optional capability activation** entry in both

‎examples/docs-governance-smoke.py‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,7 @@
2727
"README.md",
2828
"domain-capability-packs.md",
2929
"public-adoption-loop.md",
30+
"release-note-template.md",
3031
"release-readiness.md",
3132
"scenario-capability-gap-map.md",
3233
"vision.md",
@@ -157,6 +158,7 @@ def main() -> int:
157158
"docs/outreach/README.md",
158159
"docs/operations/README.md",
159160
"docs/product/README.md",
161+
"docs/product/release-note-template.md",
160162
"docs/product/foundations/README.md",
161163
"docs/product/migrations/README.md",
162164
"docs/product/roadmaps/README.md",

0 commit comments

Comments
 (0)