34 lines
2.4 KiB
Markdown
34 lines
2.4 KiB
Markdown
# 文档维护约定
|
|
|
|
适用于本目录及所有子目录。
|
|
|
|
## 文档组织
|
|
|
|
- 正文放在 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，不限制全语言。
|