54 lines
4.8 KiB
Markdown
54 lines
4.8 KiB
Markdown
# 文档维护约定
|
||
|
||
适用于本目录及所有子目录。
|
||
|
||
## 每次修改的必读入口
|
||
|
||
- 每次新增、修改或审查文档，先读取 [endor-docs skill](authoring/SKILL.md)，并从[手册入口](authoring/README.md)选择主任务与必要补充任务。阅读所选任务页、必读方法、对应 DOC 规则和目标主题主定义后再动笔；小型改动不要求通读所有资源。
|
||
- 按任务页直接查询所需方法、规则、示例与注意事项；实际阅读对应小节，不能只列出编号或跳过阅读。该流程通过 Markdown 完成。
|
||
- 结构性改写至少核对 DOC-001、002、005、015、021、024；新增页面选择适合职责的[模板](authoring/templates/README.md)，不要机械填充无关段落。
|
||
- 修改后按[检查清单](authoring/checklist.md)人工核对主定义、目录、文法、例子与规范状态。交付时记录适用规则及实际完成的检查。
|
||
- 用户未明确要求执行代码时，不运行程序、脚本、测试、构建或安装命令；skill、检查清单和现有工具都不能替代执行授权。用户明确要求的 commit、push 限于必要 Git 流程，不附带执行测试或项目 hook。
|
||
- 结构检查、人工语义核对、真实程序执行与读者测试分别报告；工具通过不代表例子已经运行。
|
||
- 文档规范不替代语言决定，不因润色、采用模板或 AI 续写而确认未定语法。
|
||
- 用户明确的新语言决定优先于旧文档，按 TASK-06 落实准确范围；用户使用 Endor 简称不自动触发正式名称与源码围栏更名。
|
||
|
||
## 文档组织
|
||
|
||
- 正文放在 guide，按概念依赖顺序编号；术语、文法、设计状态和补充说明放在 appendices。
|
||
- README 作为读者入口，提供顺序目录与查询索引，不用核心约定清单替代语言介绍。
|
||
- 每章先定义概念，再说明语法、示例和行为。内容应在未阅读讨论历史的情况下独立成立。
|
||
- 使用技术文档陈述句，不使用对话回应、提问清单、讨论过程或开发日志作为正文。
|
||
- 不在各章重复说明全书目标、全部约束和设计过程；未定规则集中维护在规范状态附录，必要的局部提案保留短注。
|
||
- 每个概念指定主要说明章节，其余章节使用引用；完整 EBNF 集中在形式文法附录。
|
||
- 修改章节位置时同步更新目录、相邻导航、术语索引、正文链接与文法。外部读者正文使用中文。
|
||
|
||
## 语言边界
|
||
|
||
- 只使用语言名称 Endorphin，不出现开发软件代称、版本或实现兼容说明。
|
||
- 文档定义源码与可观察效果，不以开发实现进度定义语言规则。
|
||
- 构建阶段固定为 Preflight，运行阶段固定为 inflight，保持大小写；定义见 guide/05-preflight-and-inflight.md。
|
||
- 两个阶段名称不自动成为源码关键字。新增语法说明必要的 Preflight 检查和 inflight 效果。
|
||
- 不设计云端实体、持久化类或自动建表。数据读取只是逻辑调用用法，不引入通信、缓存、部署与编排方案。
|
||
- 普通调用不要求业务代码额外定义 RPC 服务、监听器、协议客户端或接口描述文件。
|
||
|
||
## 示例与状态
|
||
|
||
- key 采用用户名:namespace路径，用户名唯一，路径至少一级；各层 namespace 语义一致。
|
||
- 归属通过外部 key 与索引提供，正文不声明自身 namespace。
|
||
- use 只引用完整 key，不附加选择性名称列表。
|
||
- 官方 UI 组件不列为示例用户库的内容；未定的官方引用方式不可写成免导入默认能力。
|
||
- 示例围绕商品定价展开，标明外部归属与片段位置；局部片段不能混写为完整程序。
|
||
- 名称查找、可见性和数据读取成员的假设明确说明，不虚构未确认 API。
|
||
- 已确定约定、语法提案和未定义边界统一记录在 appendices/specification-status.md；文档重构不代表语法提案被确认。
|
||
- 共用程序和表达式文法；UI 单根限制仅约束 render，不限制全语言。
|
||
|
||
## 仓库与交付
|
||
|
||
- 保留其他作者的未提交改动；共享链接使用仓库相对路径，不依赖本机目录或会话历史。
|
||
- 对 gitea.entroia.com 的操作只认证为 codex-bot。仓库 owner 不代表认证身份，不借用 owner 的账户、密钥或凭据。
|
||
- 在本仓库范围配置提交作者为 Codex Bot、codex-bot@gitea.entroia.local；SSH 使用 git 用户、22222 端口和 bot 专用密钥，以 -F /dev/null 与 IdentitiesOnly=yes 隔离其他身份。
|
||
- 密钥和其他认证材料只在各电脑安全配置，不写入仓库。权限不足时完成可进行的本地工作，再申请 bot 权限。
|
||
- 仅在用户授权时提交或推送，不强推覆盖远端。每次提交或推送后的中文报告覆盖所有改动文件及目的，并说明提交标识、推送状态、检查结果和未完成步骤。
|
||
- 完整协作流程见 [CONTRIBUTING.md](CONTRIBUTING.md)。
|