2.6 KiB
2.6 KiB
文档修改工作流
本流程适用于人工与 AI 作者。目标是把写作约定落实到每次修改，并避免无关文件或未经确认的语言决定进入提交。
1. 开始前
读取仓库 AGENTS.md、手册入口和目标主题的主要定义。检查当前分支、远端与工作区；已有未提交修改属于原作者，未经授权不清除或覆盖。
记录：
- 目标读者与本次阅读目标。
- 页面主要职责与本次改动范围。
- 适用的 DOC 规则 ID。
- 已确定语义、局部假设和未定设计。
- 预计需要同步的定义、示例、导航与状态。
2. 选择相关规则
| 改动 | 最少阅读的相关规则 |
|---|---|
| 错字、链接或术语 | DOC-017、021 |
| 新增用法与示例 | DOC-004、009、010、012、013、015、021 |
| 新增或拆分章节 | DOC-001、002、005、006、007、008、021、024 |
| 外部资料研究 | DOC-020；再根据结论选相关规则 |
| AI 或跨电脑接续 | DOC-022、023；再选任务适用规则 |
这是起点，不替代按风险判断。引用规则页见规则索引。
3. 编辑
先修改主要定义，再同步依赖内容。使用适用的模板，但不要填满与主题无关的栏目。
语法提案保持提案身份。涉及新的语言决定时，说明所需决定而不擅自补造语法。研究与作者规则放在 authoring，不混入读者语言主线。
4. 验证
在仓库根目录执行：
python3 tools/check_docs.py
python3 -m unittest discover -s tools/tests -v
git diff --check
另行核对示例计算、归属与引用、文法及局部假设，并执行读者任务检查。检查清单见 checklist.md。
工具只验证结构及有限约定，不证明语言可编译、程序正确或文档易懂。新工具的检查能力以 tools/README.md 为准。
5. 交付与提交
报告改动文件、目的、规则 ID、验证范围和未完成项目。用户要求提交或推送时：
- 检查暂存文件，排除无关编辑、个人配置与凭据。
- 使用仓库约定的作者与认证身份。
- 提交后核对提交文件与标识；推送后核对远端分支。
- 如被拒绝，保留本地提交并报告原因，不强推或改用其他账户。
6. 接续工作
另一作者从仓库文件和 Git 状态开始，不依赖聊天记忆。维护手册时保留 DOC、SRC 和 TPL 编号；新增来源先登记访问状态。