diff --git a/docs/development/release-runbook.md b/docs/development/release-runbook.md index 4eec386a..c457da32 100644 --- a/docs/development/release-runbook.md +++ b/docs/development/release-runbook.md @@ -10,6 +10,23 @@ from the authoritative GitHub, OSS, workflow, and Git state, then use the smallest existing idempotent rerun or a new immutable version as specified below. +## Optional PR Article + +Product publicity is an optional companion to a release, not a release blocker +or a replacement for the approved bilingual release notes. When requested, +follow the [PR article workflow](../pr-articles/README.md) and choose either the +[featured article](../pr-articles/featured-template.md) or +[regular update](../pr-articles/regular-template.md) template based on user value, +not version size or commit count. + +Prepare the draft and real screenshots against the candidate commit using the +[isolated screenshot procedure](../pr-articles/screenshot-guide.md). This does +not waive the build, packaging, or launch restrictions below. Keep missing +materials in the article's review record without delaying the software release. +Before external publication, verify the final version, download links, upgrade +notes, and screenshot accuracy. Preparing materials does not authorize posting +to a public channel; follow the user's explicit publication instruction. + ## Release Packaging - Unless the user explicitly requests it, never run a local production build, diff --git a/docs/pr-articles/README.md b/docs/pr-articles/README.md new file mode 100644 index 00000000..dae1c4b0 --- /dev/null +++ b/docs/pr-articles/README.md @@ -0,0 +1,107 @@ +# GoodBuddy PR 宣传文章工作流 + +本文件用于 GoodBuddy 项目的产品宣传文章。这里的 PR 指产品传播,不指 GitHub Pull Request。 +它是项目工作约定,不属于随应用分发的 Skill,不要求修改产品代码。 + +## 触发与范围 + +用户说“准备本轮 PR”“按上一个 tag 写发布文章”或要求重点功能宣传时,执行本流程。 +默认交付文章和素材,不自动提交 Git、打版本 tag、发布版本或向外部平台发文。 +版本发布操作遵循 [发布手册](../development/release-runbook.md)。本流程是可选配套,不阻塞软件发布。 + +配套文档: + +- [重点 PR 模板](./featured-template.md):介绍一项值得专门展开的能力。 +- [常规 PR 模板](./regular-template.md):介绍小功能、体验改善和维护修复。 +- [截图步骤](./screenshot-guide.md):隔离环境准备、真实操作与素材取证。 + +先读取仓库指引、Git 状态、桌面版本 tag 和提交历史。默认比较当前分支最近的正式桌面 +tag 与当前 HEAD;明确记录基线 tag、目标提交和检查日期。Agent tag 单独核对,不混作桌面基线。 +若 HEAD 已位于正式 tag,先根据用户所指的发布版本确定比较区间,不能默默换成另一轮发布。 + +未提交改动单列,不将设计文档、原型、计划或仅有接口的实现算作已交付能力。 +保留用户工作区改动。全文不得把候选提交写成已经发布或可以下载的版本。 + +## 核查与选题 + +提交信息和 `Release note:` 是线索,实际 diff、最终代码和验证记录是事实依据。 +每项候选内容记录: + +- 目标用户和具体任务。 +- 原有行为、本轮变化及使用入口。 +- 前提、限制、持久化范围、数据流向、费用和升级兼容性中实际相关的内容。 +- 对应提交、代码或文档位置,以及已有验证的范围。 + +将已知验证记录与本轮实际运行结果分开。定向测试通过不能写成全量通过,组件 fixture +不能写成完整应用端到端通过。发现失败如实记录,不为写文章擅自修复源码。 + +先选择重点 PR 或常规 PR,不按版本号大小、提交数量或凑足篇幅决定类型。 +重点 PR 围绕一项能力或同一使用场景展开;常规 PR 按重要性介绍本轮变化,可以只有几段。 +给出类型、推荐标题和推荐理由。维护修复可以只进入更新日志;变化不足以支撑文章时,明确建议暂不单独发文。 +已有能力可以作为场景背景,但不能包装成本轮新增。 + +## 自动截图与演示 + +截图是工作流的实际执行步骤,不能默认把任务留给用户。 +按[截图步骤](./screenshot-guide.md)准备隔离环境,并遵循其中链接的项目自动化规范。 +先检查现有应用启动、Electron 自动化和截图工具,复用已验证的机制。 +根据选题编排一个短的真实操作过程,记录每张图片要证明的行为,再执行和截图。 + +优先使用对应版本的运行应用或已有构建,并使用独立演示配置与公开、虚构的测试资料。 +记录应用版本或构建提交;已有构建落后于目标源码时,不能把截图标为目标版本。 +不要为截图修改应用源码、产品默认配置、用户数据库或用户正在工作的会话。 +确需临时自动化脚本时放在独立临时目录,不加入产品实现或分发目录。 +构建与打包遵循仓库约定,不能为了截图绕过发布流程中的本地构建限制。 + +可用的浏览器工具可用于可访问的网页与 Web 演示;桌面应用截图使用已有 Electron +自动化能力或其他实际可用的桌面工具。不能假定网页浏览器工具能控制 Electron 应用。 + +截图要求: + +- 使用真实界面和实际结果;不修改 DOM、伪造任务状态或拼接理想答案冒充实测。 +- 产品主截图优先来自正常 UI 到真实实现的完整路径。组件 fixture 或原型只作明确标注的辅助图。 +- 操作后等待页面加载、目标状态和布局稳定,再截图。逐张读取图片,检查可读性、裁切和状态。 +- 避免真实客户信息、私人会话、凭据和内部地址。优先重新使用演示数据拍摄,必要脱敏须注明。 +- 裁切、缩放和标注不能改变产品含义;保存原图,并区分原图与发布用图片。 +- 使用统一窗口大小、主题和演示命名。图注说明操作与结果,避免只写“功能截图”。 +- 调用收费模型、访问外部系统或执行写操作时,遵循当前会话已有授权及工具要求。 + +自动化不可用、版本不匹配或正常路径无法完成时,记录具体阻碍,继续完成独立的核查和写作。 +缺少的图片写入内部待补清单,不能声称截图已完成,也不能用原型替代后隐去说明。 + +## 写作与审校 + +采用所选模板。重点 PR 尽早介绍能力和使用条件,围绕真实演示展开;常规 PR 直接说明变化, +有必要才解释原来的不便。没有具体背景材料时不虚设场景,不为小改动反复解释价值。 + +模板中的编辑提示不能变成固定话术。不要求每篇都出现“比如你正在……”“这意味着……”或 +“如果你经常……可以试试”。不强行总结、升华或配平段落;常规 PR 可省略小标题。 +篇幅按内容决定,图片用于说明具体变化,不为装饰而凑数。 +升级风险集中放在体验入口附近,详细修复链接到完整更新日志。 + +不编造效率数字、用户评价、客户案例或测试结果。不使用“永不错过”“完全避免”等超出 +机制范围的承诺。持久保存、当前运行期间保留、跨项目可见和跨设备同步必须准确区分。 + +可用时使用 `deai-writing` 技能审校正文;无该技能时人工检查空泛形容词、模板化转折、 +机械排比和重复总结。审校不能删除必要的能力边界和升级提示。 + +## 交付与发布核对 + +用户指定位置时按指定位置交付,否则将本轮材料放在 +`docs/pr-articles/drafts/<日期>-<主题>/`。目录只包含本轮文章与必要素材,不改产品代码。 + +最小交付: + +- `article.md`:文章标题、正文、相对路径配图和图注。 +- `assets/`:实际取得的图片;如有处理,保留可区分的原图。 +- `review.md`:比较区间、选题理由、事实来源、截图环境与步骤、验证范围和待补事项。 + +没有图片时不建空目录。文章草稿中的素材占位必须醒目标注;发布用正文不得留下占位文字。 +内部验证细节和编辑备注放在 `review.md`,不混入面向用户的宣传正文。 + +交付前检查图片可读、相对路径存在、文章与图片一致、标题没有超出功能事实。 +发布前再次确认对应版本可下载、下载链接有效、升级说明准确,且最终版本没有改变演示行为。 +尚未发布时保持草稿状态,不编造版本号或上线时间。 + +最终回复提供文章和素材位置,概括推荐主题、实际截图情况及剩余阻碍。 +只有得到明确发布指令后,才通过可用平台能力执行外部发布;准备文章不等于授权发布。 diff --git a/docs/pr-articles/featured-template.md b/docs/pr-articles/featured-template.md new file mode 100644 index 00000000..893e282d --- /dev/null +++ b/docs/pr-articles/featured-template.md @@ -0,0 +1,35 @@ +# 重点 PR 模板 + +适用于新增一项值得专门介绍的能力,或明显改变某种工作方式的更新,例如外部知识库接入。 +围绕一个主题,用真实任务和结果说明能力。没有必要不铺背景,不编造用户经历或设计动机。 + +写作前在本轮 `review.md` 记录目标读者、实际任务、本轮变化、主要证据、使用条件和文章取舍。 +方括号是编辑提示,发布前删除或替换。各节按内容增删,不规定字数和功能数量。 + +```markdown +# [具体功能或用途,版本号可放副标题] + +[直接介绍本次新增的能力、适用的人和使用条件。] + +## [一个实际任务] + +[使用公开或明确标识的演示资料,说明准备完成什么任务。] + +![说明图片内容的替代文本](assets/实际图片文件名.png) + +[图注说明实际操作或结果。] + +[结合操作结果介绍功能。截图能看懂的内容不重复说明,正文补充必要解释。] + +## [值得单独解释的能力或设计选择,可省略] + +[根据功能展开。设计原因须有依据,不虚构用户反馈或研发故事。] + +[影响使用的前提、费用、数据流向或限制,按实际需要说明。] + +[可用版本、体验入口、使用文档。] +[必要的升级说明。] +``` + +审校时检查:标题是否超出实际能力;演示是否支撑主要结论;是否混入无关的小更新; +是否重复描述同一价值。配图按[截图步骤](./screenshot-guide.md)取得,完整流程见[工作流](./README.md)。 diff --git a/docs/pr-articles/regular-template.md b/docs/pr-articles/regular-template.md new file mode 100644 index 00000000..d3cc39c9 --- /dev/null +++ b/docs/pr-articles/regular-template.md @@ -0,0 +1,33 @@ +# 常规 PR 模板 + +适用于小功能、体验改善和维护修复,例如会话置顶、完成提示和浏览器交互改善。 +开头概括本轮更新,再按重要性说明变化。可以介绍不同功能,不要求拼成一个故事。 +只有两三个小变化时,可以去掉小标题,用几段文字写完;纯维护更新也可只保留更新日志。 + +写作前在本轮 `review.md` 记录比较区间、入选变化、事实来源和使用限制。 +方括号是编辑提示,发布前删除或替换。不规定字数,各项篇幅不要求一致。 + +```markdown +# GoodBuddy 更新:[本轮最值得关注的一两项变化] + +[一两句话说明本轮更新了什么,直接进入内容;信息重复时省略。] + +## [变化名称] + +[说明现在能怎样操作。必要时用一句话交代原来的不便,不重复解释价值。] + +[有助于理解时配实际截图和简短图注。] + +## [变化名称] + +[同上,按重要性排序。] + +[其他小改动可合并成简短列表,不必每项单独成节。] + +[可用版本与下载入口。] +[必要的升级说明,完整更新日志链接。] +``` + +审校时删掉空泛开场、虚设场景和总结口号。不为小修复强行写产品意义,不把旧能力写成新增。 +明显的界面变化可以配图,其余直接说明。配图按[截图步骤](./screenshot-guide.md)取得, +完整流程见[工作流](./README.md)。 diff --git a/docs/pr-articles/screenshot-guide.md b/docs/pr-articles/screenshot-guide.md new file mode 100644 index 00000000..1b9b862c --- /dev/null +++ b/docs/pr-articles/screenshot-guide.md @@ -0,0 +1,58 @@ +# PR 文章截图步骤 + +本页规定宣传素材的准备顺序。隔离启动和自动化实现以 +[Electron UI 自动化规范](../quality/electron-ui-automation.md#3-当前源码与隔离启动)为准, +不重复维护另一套测试机制。目前仓库没有通用的一键完整 App 截图命令;执行者需要复用或 +按规范准备临时驱动,不能将下面的流程描述当作已经实现的自动化脚本。 + +## 1. 确认版本和素材 + +从仓库根目录检查 `git rev-parse HEAD`、`git status --short`、`node --version` 和 +`node -p "require('electron/package.json').version"`。依赖缺失时按 +[开发与构建](../../BUILD.md)准备,不重复安装已满足的依赖。 + +在本轮 `review.md` 中记录目标提交、实际构建来源、平台、语言、主题、缩放和截图清单。 +优先采用 1280×800 内容区、统一主题与中文界面,按演示需要调整,并记录实际尺寸。 +每张图先写清要说明的动作和结果。重点 PR 优先连续演示,常规 PR 只拍需要解释的界面变化。 + +## 2. 准备隔离环境 + +使用本轮专用临时目录,包含 profile、演示工作区、驱动和原始截图。不要复制整套私人会话。 +仅使用公开或明确虚构的演示资料,凭据沿用已授权的安全配置方式,不写入文档、脚本或图片。 + +使用可确认属于目标版本的产物。`npm start` 只预览已有产物,不自动重建,也不自动隔离数据; +`npm run dev` 同样不能代替隔离启动器。`GOODBUDDY_WORKSPACE` 只指定工作区,不隔离用户数据库。 +不存在可直接假定有效的 `GOODBUDDY_TEST_MODE` 或 `GOODBUDDY_USER_DATA` 开关。 + +开发场景的构建方法见自动化规范;发布准备遵循[发布手册](../development/release-runbook.md), +宣传材料不自动授权本地生产构建、打包或 packaged-app 探测。没有匹配产物时记录缺口, +继续其他材料准备,不能将旧产物截图标成新版本。 + +## 3. 启动与操作 + +按自动化规范准备独立 Node supervisor 和 Electron bootstrap: + +1. 在 Electron ready 之前设置专用 `userData`、`sessionData` 和日志路径,再动态导入对应产物的 + `out/main/index.js`,由生产 Main 创建窗口并加载真实 Preload、Renderer。 +2. supervisor 从仓库解析 Electron,清除子进程环境中的 `ELECTRON_RUN_AS_NODE`,设置有限期限。 + 检查最终用户数据路径仍在临时目录,避免便携模式覆盖隔离配置。 +3. 按实际临时驱动路径执行 `node "<本轮临时目录>/run.mjs"`。这是驱动适配完成后的命令模板, + 不是仓库现成入口。记录驱动来源、实际命令、入口文件与构建身份。 +4. 从正常 UI 创建演示项目、会话和配置。通过 Electron 输入 API 操作,等待目标状态、字体和布局 + 就绪后使用 `capturePage().toPNG()` 截图。不能注入完成事件或假答案替代真实任务。 + +现有 `node build/run-browser-tabs-electron-e2e.cjs` 可供参考启动与进程监督方式, +但它是浏览器服务集成测试,不是完整应用截图命令。网页浏览器工具也不能直接当作桌面控制器。 +组件 fixture 只能作为明确标注的辅助示意,不作为主功能完成的证据。 + +## 4. 审阅与归档 + +逐张打开原图,检查文字可读、菜单没有遮挡关键内容、状态和正文描述一致,以及是否含私人数据。 +对原生浏览器视图等复合界面,确认截图实际包含要展示的内容;不能仅凭 PNG 文件存在判定成功。 +保存原图,裁切或标注另存;处理不能改变产品含义。 + +将采用的图片放入本轮 `assets/`,用相对路径写进文章。`review.md` 记录操作步骤、文件名、 +实际观察结果、图片审阅情况及模型/服务调用情况。失败时保留阶段和脱敏诊断,列出待补素材。 +先归档必要材料,再停止本轮进程、服务并清理临时 profile;不得按进程名批量结束用户应用。 + +发布前核对最终版本行为是否仍与截图一致;有变化则重拍受影响部分。