Lina Community Release Changelog

Lina Release Changelog

手动生成 LinaPro 版本更新日志。当前阶段仅用于人工执行和质量验证，不接入 CI、GitHub Actions 或自动发布流程。

核心原则

1. 只手动执行：不得自动创建 GitHub Release、推送标签、提交文件或修改任何 .github/workflows/ 文件。
2. 固定输出路径：生成结果必须写入仓库根目录 localdocs/changelog.md。
3. 固定模板：英文内容在上，中文内容在下，中间使用模板分割线；不得新增模板外章节。
4. 证据优先：必须基于 Git 历史、源码差异、OpenSpec 内容和 GitHub bug 标签 issue 审查整理；不得依赖 PR 标识或发布说明字段作为唯一依据。
5. 详尽覆盖：输出面向发布人员和用户，不是提交摘要；必须覆盖比较范围内关键功能、修复、数据库结构或初始化数据变化，以及工具链体验变化。
6. 双语一致：英文和中文分别完整成文，事实覆盖一致，不交叉混写。
7. 表达自然：英文和中文都必须地道、清晰、流利、易懂；按目标语言重新组织句子，不做生硬直译，不使用少见、拗口或容易误解的词语。
8. 尊重工作区：执行前查看 git status --short。除 localdocs/changelog.md 外，不修改无关文件；不要还原用户已有改动。

输入范围

支持两种用法：

用户可能使用以下表达：

• 生成当前版本更新日志
• 生成 v0.1.0 到 v0.2.0 的 changelog
• 比较 v0.2.0 和 v0.1.0
• from=v0.1.0 to=v0.2.0
• v0.1.0..v0.2.0

执行流程

1. 确认环境

在仓库根目录执行只读检查：

pwd
git status --short
git tag --list

如果当前目录不是 LinaPro 仓库根目录，或 git 不可用，停止并说明原因。

2. 解析比较范围

默认范围

未指定范围时：

1. 将 to 设为 HEAD。
2. 从 git tag --merged HEAD 中找出可达发布标签，发布标签通常匹配 vMAJOR.MINOR.PATCH 或 vMAJOR.MINOR.PATCH-prerelease。
3. 选择早于 to 的最近发布标签作为 from。如果 HEAD 正好带有发布标签，不要把同一个标签作为 from；应选择它之前的最近可达发布标签。
4. 如果找不到可用 from，停止并说明无法确定默认比较范围，要求用户显式指定两个引用。

显式双引用范围

用户指定两个引用时：

1. 使用 git rev-parse --verify "<ref>^{commit}" 验证两个引用都存在。
2. 如果用户明确提供 from=<ref> 和 to=<ref>，优先尊重该方向，但必须确认该方向可验证：
   • from 是 to 的祖先时，方向有效。
   • 两者都是语义化发布标签且 from 的版本号早于 to 时，方向有效，即使仓库历史经过压缩导致二者不是线性祖先关系。
   • 如果 from 的版本号晚于 to，停止并说明用户给出的方向与版本顺序相反，建议改用无方向的比较表达或交换参数。
   • 如果既不能通过祖先关系验证，也不能通过语义化发布标签顺序验证，停止并说明范围不安全。
3. 如果用户只说“比较 A 和 B”，则通过祖先关系规范化方向：
   • A 是 B 的祖先时，使用 A..B。
   • B 是 A 的祖先时，使用 B..A。
   • 两者互不为祖先时，只有在二者都是可比较的语义化发布标签且顺序明确时才按版本号排序；否则停止并说明无法安全判断方向。
4. 使用 git rev-list --count <from>..<to> 确认范围非空；如果为 0，停止并说明没有可生成的变更。

标题版本

标题中的版本使用以下优先级：

1. 如果 to 是发布标签，使用该标签，例如 v0.2.0。
2. 如果 to 是 HEAD 且当前 HEAD 有发布标签，使用该标签。
3. 否则读取 apps/lina-core/manifest/config/metadata.yaml 中的 framework.version。
4. 如果仍无法确定，使用 Unreleased。

3. 收集证据

不要只读取 git log --oneline。至少收集以下信息：

git log --first-parent --decorate --date=short --format="%h %ad %s" <from>..<to>
git log --decorate --date=short --format="%h %ad %s" <from>..<to>
git diff --stat <from>..<to>
git diff --name-status <from>..<to>

然后按变更路径分组，重点阅读这些目录中的关键文件或差异：

• .agents/skills/
• .github/
• openspec/
• hack/tools/
• hack/makefiles/
• apps/lina-core/manifest/sql/
• apps/lina-core/
• apps/lina-vben/
• apps/lina-plugins/*/manifest/sql/
• apps/lina-plugins/
• README.md 和 README.zh-CN.md

对于重要提交，使用 git show --stat <commit> 和必要的源码片段确认真实行为。提交标题只能作为线索，不能作为关键内容的唯一证据。

GitHub bug issue 证据

生成 Bug Fixes/Bug 修复前，必须审查上一次版本到本次版本之间的 GitHub bug 标签 issue，避免只从代码差异推断修复列表。优先使用比较两端提交日期作为查询窗口，分别查询在窗口内创建、更新或关闭的 bug issue：

git log -1 --format=%cI <from>
git log -1 --format=%cI <to>
gh issue list --state all --label bug --search "created:YYYY-MM-DD..YYYY-MM-DD" --json number,title,state,labels,createdAt,updatedAt,closedAt,url
gh issue list --state all --label bug --search "updated:YYYY-MM-DD..YYYY-MM-DD" --json number,title,state,labels,createdAt,updatedAt,closedAt,url
gh issue list --state all --label bug --search "closed:YYYY-MM-DD..YYYY-MM-DD" --json number,title,state,labels,createdAt,updatedAt,closedAt,url
gh issue list --state open --label bug --json number,title,state,labels,createdAt,updatedAt,closedAt,url

将上述结果按 issue 编号合并去重。当前仍打开的 bug issue 中，若报告时间早于或落入比较范围，且问题表现与本次源码差异、测试或 OpenSpec 语义匹配，也必须纳入候选。如果提交信息引用了 issue 编号，也必须纳入候选：

git log --format="%H %s%n%b" <from>..<to> | rg "#[0-9]+"

对每个候选 bug issue，使用 gh issue view <number> --comments 或 GitHub 页面读取标题、正文和必要评论，确认实际问题表现。判断是否已修复时不得以 issue 是否关闭为准；关闭状态只能作为线索。必须结合比较范围内的提交、源码差异、OpenSpec、测试结果或可执行的功能验证判断：

• 如果代码提交或最终实现已经解决 issue 描述的问题，且有测试、源码路径或手动验证依据，即使 issue 仍处于打开状态，也应写入 Bug Fixes/Bug 修复。
• 如果 issue 已关闭但代码范围、测试或功能验证无法证明问题已修复，不要把它写成已修复；在保守处理说明中记录无法确认。
• 如果本地没有 gh、没有 GitHub 权限或网络不可用，不能断言没有 bug issue 修复；必须在证据来源摘要和保守处理说明中记录 GitHub bug issue 审查受限。

插件 submodule 证据

apps/lina-plugins/是父仓库中的submodule时，父仓库的git diff只能显示gitlink指针变化，不能展示插件仓库内部提交和文件差异。只要git diff --name-status <from>..<to>包含apps/lina-plugins，或git ls-files -s apps/lina-plugins显示该路径的mode为160000，必须解析submodule两端commit并进入插件仓库收集证据：

git ls-tree <from> apps/lina-plugins
git ls-tree <to> apps/lina-plugins
git -C apps/lina-plugins rev-parse --verify "<old-plugin-commit>^{commit}"
git -C apps/lina-plugins rev-parse --verify "<new-plugin-commit>^{commit}"
git -C apps/lina-plugins log --decorate --date=short --format="%h %ad %s" <old-plugin-commit>..<new-plugin-commit>
git -C apps/lina-plugins diff --stat <old-plugin-commit>..<new-plugin-commit>
git -C apps/lina-plugins diff --name-status <old-plugin-commit>..<new-plugin-commit>

如果本地submodule缺少比较端commit，先执行只更新插件仓库Git对象的读取性拉取，再重试验证：

git -C apps/lina-plugins fetch --tags --prune origin

如果拉取失败或commit仍不可用，不得断言插件无变化；必须在证据来源摘要和保守处理说明中记录无法确认的submodule范围。如果old-plugin-commit与new-plugin-commit相同，记录父仓库比较范围内没有已提交的插件指针变化；git -C apps/lina-plugins status --short只能作为工作区状态提示，不能把未提交的插件工作区改动写入发布变更。

不要把父仓库中的M apps/lina-plugins或gitlink指针本身写成发布功能。插件发布说明必须来自插件仓库内部提交、文件差异、OpenSpec或源码事实。