docs: add product PR workflow and article templates
This commit is contained in:
mesalogo
@@ -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,
|
||||
|
||||
@@ -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`，不混入面向用户的宣传正文。
|
||||
|
||||
交付前检查图片可读、相对路径存在、文章与图片一致、标题没有超出功能事实。
|
||||
发布前再次确认对应版本可下载、下载链接有效、升级说明准确，且最终版本没有改变演示行为。
|
||||
尚未发布时保持草稿状态，不编造版本号或上线时间。
|
||||
|
||||
最终回复提供文章和素材位置，概括推荐主题、实际截图情况及剩余阻碍。
|
||||
只有得到明确发布指令后，才通过可用平台能力执行外部发布；准备文章不等于授权发布。
|
||||
@@ -0,0 +1,35 @@
|
||||
# 重点 PR 模板
|
||||
|
||||
适用于新增一项值得专门介绍的能力，或明显改变某种工作方式的更新，例如外部知识库接入。
|
||||
围绕一个主题，用真实任务和结果说明能力。没有必要不铺背景，不编造用户经历或设计动机。
|
||||
|
||||
写作前在本轮 `review.md` 记录目标读者、实际任务、本轮变化、主要证据、使用条件和文章取舍。
|
||||
方括号是编辑提示，发布前删除或替换。各节按内容增删，不规定字数和功能数量。
|
||||
|
||||
```markdown
|
||||
# [具体功能或用途，版本号可放副标题]
|
||||
|
||||
[直接介绍本次新增的能力、适用的人和使用条件。]
|
||||
|
||||
## [一个实际任务]
|
||||
|
||||
[使用公开或明确标识的演示资料，说明准备完成什么任务。]
|
||||
|
||||
|
||||
|
||||
[图注说明实际操作或结果。]
|
||||
|
||||
[结合操作结果介绍功能。截图能看懂的内容不重复说明，正文补充必要解释。]
|
||||
|
||||
## [值得单独解释的能力或设计选择，可省略]
|
||||
|
||||
[根据功能展开。设计原因须有依据，不虚构用户反馈或研发故事。]
|
||||
|
||||
[影响使用的前提、费用、数据流向或限制，按实际需要说明。]
|
||||
|
||||
[可用版本、体验入口、使用文档。]
|
||||
[必要的升级说明。]
|
||||
```
|
||||
|
||||
审校时检查：标题是否超出实际能力；演示是否支撑主要结论；是否混入无关的小更新；
|
||||
是否重复描述同一价值。配图按[截图步骤](./screenshot-guide.md)取得，完整流程见[工作流](./README.md)。
|
||||
@@ -0,0 +1,33 @@
|
||||
# 常规 PR 模板
|
||||
|
||||
适用于小功能、体验改善和维护修复，例如会话置顶、完成提示和浏览器交互改善。
|
||||
开头概括本轮更新，再按重要性说明变化。可以介绍不同功能，不要求拼成一个故事。
|
||||
只有两三个小变化时，可以去掉小标题，用几段文字写完；纯维护更新也可只保留更新日志。
|
||||
|
||||
写作前在本轮 `review.md` 记录比较区间、入选变化、事实来源和使用限制。
|
||||
方括号是编辑提示，发布前删除或替换。不规定字数，各项篇幅不要求一致。
|
||||
|
||||
```markdown
|
||||
# GoodBuddy 更新：[本轮最值得关注的一两项变化]
|
||||
|
||||
[一两句话说明本轮更新了什么，直接进入内容；信息重复时省略。]
|
||||
|
||||
## [变化名称]
|
||||
|
||||
[说明现在能怎样操作。必要时用一句话交代原来的不便，不重复解释价值。]
|
||||
|
||||
[有助于理解时配实际截图和简短图注。]
|
||||
|
||||
## [变化名称]
|
||||
|
||||
[同上，按重要性排序。]
|
||||
|
||||
[其他小改动可合并成简短列表，不必每项单独成节。]
|
||||
|
||||
[可用版本与下载入口。]
|
||||
[必要的升级说明，完整更新日志链接。]
|
||||
```
|
||||
|
||||
审校时删掉空泛开场、虚设场景和总结口号。不为小修复强行写产品意义，不把旧能力写成新增。
|
||||
明显的界面变化可以配图，其余直接说明。配图按[截图步骤](./screenshot-guide.md)取得，
|
||||
完整流程见[工作流](./README.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；不得按进程名批量结束用户应用。
|
||||
|
||||
发布前核对最终版本行为是否仍与截图一致；有变化则重拍受影响部分。
|
||||
Reference in New Issue
Block a user