diff --git a/docs/zh/contribute/contribution_process.md b/docs/zh/contribute/contribution_process.md index 34cb702f21535bcd7e79feadec65571851344800..6a76b93b03dc14e339246369f8880f5a39576e2d 100644 --- a/docs/zh/contribute/contribution_process.md +++ b/docs/zh/contribute/contribution_process.md @@ -170,6 +170,6 @@ ## 文档暂不在文档中心发布 -如果开发者所创作的文档内容,暂时不适合推广或尚不成熟,目前无需发布在文档中心,可在文档仓的 [archive](https://gitee.com/openeuler/docs/tree/25.03/Archive) 目录中进行增删改。等到需要发布时,再将其移至合适的目录,注意这类文档同样需要遵循写作规范。 +如果开发者所创作的文档内容,暂时不适合推广或尚不成熟,目前无需发布在文档中心,可在文档仓的 [archive](https://gitee.com/openeuler/docs/tree/25.03/archive) 目录中进行增删改。等到需要发布时,再将其移至合适的目录,注意这类文档同样需要遵循写作规范。 > 注意:提交至 archive 目录的文档,按计划未来会发布到文档中心,若长时间无人维护,将会被清理。 diff --git "a/docs/zh/contribute/figures/\346\211\213\345\206\214\346\230\257\346\234\200\345\260\217\347\262\222\345\272\246.png" "b/docs/zh/contribute/figures/\346\211\213\345\206\214\346\230\257\346\234\200\345\260\217\347\262\222\345\272\246.png" new file mode 100644 index 0000000000000000000000000000000000000000..801ea57bc3f0ab03f07bd80e01d6ba9d823f13dc Binary files /dev/null and "b/docs/zh/contribute/figures/\346\211\213\345\206\214\346\230\257\346\234\200\345\260\217\347\262\222\345\272\246.png" differ diff --git "a/docs/zh/contribute/\346\226\207\346\241\243\344\270\213\346\262\211\350\207\263SIG\347\273\204.md" "b/docs/zh/contribute/\346\226\207\346\241\243\344\270\213\346\262\211\350\207\263SIG\347\273\204.md" new file mode 100644 index 0000000000000000000000000000000000000000..9559159ded2c1907257be493cd7ef0fff585a42f --- /dev/null +++ "b/docs/zh/contribute/\346\226\207\346\241\243\344\270\213\346\262\211\350\207\263SIG\347\273\204.md" @@ -0,0 +1,86 @@ +# 文档生产下沉至SIG组 + +## 重要事项 + +- 文档生产下沉至各 SIG 组后,各 SIG 组需重视文档质量,更新内容时请通知 doc-sig 成员检视(测试人员测试),通过后再合入。 +- 文件名和文件夹名请使用英文小写字母、并用下划线连接(同一篇文档的中英文名保持一致),文档发布至官网后不可更改存放路径,如需更改需评审。 + +## 概述 + +之前所有文档都集中存于 docs 仓。改版后,基础特性文档依旧存放在 docs 仓,由 doc-sig 集中管理,增量特性文档在各特性 SIG 的代码仓维护。分散在各特性代码仓的文档,需通过在 docs 仓的配置文件(_toc.yaml)中添加引用,实现发布至官网。 + +![image](figures/架构图.png) + +## 约束 + +- 分版本写文档,openEuler 各版本均有独立配套文档。 +- 文档发布后仍会持续更新,如修正低级错误、内容错漏等问题。 +- 各 SIG 组负责维护特性文档,要求各 SIG 清晰掌握特性在各版本中的分布情况。 +- 各 SIG 组自主规划文档,明确区分发布至官网的文档和仅在代码仓展示的文档。 +- SIG 组维护文档以手册为最小单元(如服务器场景《A-Ops用户指南》),单本手册不得拆分存储,同一仓库可容纳多本手册。 +- 所见即所得,在 gitee 仓库可直接查看文档内容,呈现效果与最终展示一致。 + + ![image](figures/手册是最小粒度.png) + +## 要求 + +无论各 SIG 如何组织文档,如果文档要发布至官网,需要满足如下条件: + +- 在仓库根目录下创建 docs 目录,并在 docs 目录下的 zh/ 和 en/ 目录中存放需发布至官网的中英文文档,结构如下: + + ```text + ├─docs/ + | ├─zh/ + | └─en/ + ``` + + 注明:存放于 docs/zh 和 docs/en 下的文档均为发布至官网文档中心的文档,必须通过文档流水线,才能合入;若文档仅在仓库内展示、无需发布至官网,不建议存放于上述目录,可在 docs/ 下创建其他目录存放。 + +- 在 openeuler/docs 仓库中,找到对应场景的 _toc.yaml 文件,并按照指定格式添加文档的索引地址: + + upstream: 填写手册的目录结构文件(_toc.yaml)索引地址 + path(可选,默认值是“./仓库名”): 设置手册的url访问路径 + + 示例: + upstream: + path: ./openstack + +- 文档须严格对应当前版本特性,禁止包含未发布的特性或功能。 +- 支持文档的长期更新维护,确保 openEuler 新版本发布后,历史版本文档仍保持准确完整。 + +## 方案 + +为满足上述条件,建议的实现方案如下: + +- 每个 SIG 组特性应该有自己的独立代码仓库,该仓库承载该SIG的特性文档、readme、contribute等内容。 +- 在不同分支下维护对应版本的文档或创建目录维护不同版本的文档。 +- 若选择创建目录维护不同版本的文档,其内容如下: + + ```text{7-9} + ├─docs/ + | ├─zh/ + | | ├─2409/ + | | | ├─_toc.yaml + | | | ├─xxx.md + | | | └─xxx/ + | | | └─xxx.md + | | └─2503/ + | | ├─_toc.yaml + | | ├─xxx.md + | | └─xxx/ + | | └─xxx.md + | └─en/ + | ├─2409/ + | └─2503/ + ``` + +## 文档下沉流程 + +1. SIG 组确定方案,明确文档存放仓库及版本区分方式。 +2. 为仓库配置文档流水线。 +3. 将相关文档从 openeuler/docs 仓库迁移至目标仓库。 +4. 待 doc-sig 成员检视通过后,由SIG组自行安排合入。 + +## 英文翻译 + +合入中文文档 PR 后,系统将自动生成翻译 issue 并排入处理队列,翻译人员会按顺序完成英文翻译并提交PR,需各 SIG 组 Maintainer 审核合入。如需加急翻译,请将对应中文文档 PR 链接同步至 doc-sig 协调优先处理。