文档编写格式约定 Convention

存放形式

所有文档存放于 pages 目录下；
按照对应的模块可建立对应的子目录，如 core；
文档格式均为 Markdown(.md|.mdx)；
命名遵循 ${序号}.${英文简写，空格由_代替}.md 的格式；
编写完成的文档需要补充到外层 README 的目录中。

语言与排版

所有文档的第一语言均为中文；
文字排版请遵守中文文案排版指北；
- 亦可参考进行过修订的这篇；
- 其中的争议部分，如非必要，建议仍参照执行，减少因个人习惯造成的风格差异。
Markdown 编写第一行格式为 # ${中文标题} ${英文标题，首字母大写}；
Markdown 文件使用 markdownlint 确保格式正确。
- Visual Studio Code 插件十分有用。

习惯要求

请在编写时一直使用 一般时态 和 第二三人称，避免使用 我、我们 以及所在组织的名称；
文档风格参考中文技术文档写作风格指南。

归档规则

文档的最新版本应当被更新到 master 分支；
master 分支的最新 HEAD 应当是唯一有效的版本；
新的文档草稿通过以 draft/ 开始的临时分支予以管理和协作，按里程碑管理；
正式文档通过以 wip/ 开始的临时分支予以管理和协作，较小的改动可以通过 Pull Request 机制予以提交；
相关历史文档的归档通过 Git Tag 形式予以保留。