diff --git a/docs/zh/contribute/_menu.md b/docs/zh/contribute/_menu.md new file mode 100644 index 0000000000000000000000000000000000000000..5490a02e3da358708691f33ddb7f4991f177d7b7 --- /dev/null +++ b/docs/zh/contribute/_menu.md @@ -0,0 +1,15 @@ +--- +label: '文档开发指南' +ismanual: 'Y' +children: + - label: '概述' + href: './directory_structure_introductory.md' + - label: '快速入门' + href: './contribution_process.md' + - label: '教程' + children: + - label: '文档写作规范' + href: './documentation_writing_specifications.md' + - label: '文档发布流水线门禁' + href: './ci_rules.md' +--- \ No newline at end of file diff --git a/docs/zh/contribute/ci_rules.md b/docs/zh/contribute/ci_rules.md new file mode 100644 index 0000000000000000000000000000000000000000..4d59ad3ae1785cbbfa294498da2cded385c0efbb --- /dev/null +++ b/docs/zh/contribute/ci_rules.md @@ -0,0 +1,83 @@ +# 文档开发流水线门禁 + +## markdownlint + +markdownlint 是一款检查 markdown 文件格式的工具。markdownlint规则介绍及本仓规则设置，请参考[检查规则](./markdownlint_rules.md)。可使用[工具](./markdownlint_tools.md)对markdownlint 进行批量修复。 + +> 说明： +> 开发者需要确保提交的文档已修复所有markdownlint错误，否则CI门禁报错，将无法合入。 + +## 标签闭合 + +链接、表格等内容元素建议使用markdown语法书写。如果需要使用HTML样式，请确保标签闭合。 + +错误示例 + + ```yaml + + + + + +
Header 1 + Header 2
Data 1 + Data 2
+ ``` + +正确示例 + + ```yaml + + + + + + + + + +
Header 1Header 2
Data 1Data 2
+ ``` + +> 说明：开发者需要确保提交的文档中HTML 标签已全部闭合，否则CI门禁报错，将无法合入。 + +## 引用链接 + +图片、网站、手册链接请检查路径地址是否正确。 + +反例 + +- 失效的网站链接 + + ```text + [错误官网](https://doc.openeuler.org/zh/) + ``` + +- 错误的相对路径 + + ```text + [写作规范](../写作规范.md) + ``` + +​ +正例 + +- 网站链接 + + ```text + [错误官网](https://docs.openeuler.org/zh/) + ``` + +- 相对路径 + + ```text + [写作规范](./contribute/写作规范.md) + ``` + +>说明：开发者需要确保提交的文档中链接有效，否则CI门禁报错，将无法合入。 + +## 静态检查 + +新增文档时，为了能在openEuler 文档官网展示，需要在_menu.md文件增加对应文档位置。 + +>说明：开发者需要确保提交新增文档同步提交了_menu.md文件修改，否则CI门禁报错，将无法合入。 diff --git a/docs/zh/contribute/contribution_process.md b/docs/zh/contribute/contribution_process.md new file mode 100644 index 0000000000000000000000000000000000000000..cd085f91c6fec9e40e9532e9a65d51e6a0db5ed3 --- /dev/null +++ b/docs/zh/contribute/contribution_process.md @@ -0,0 +1,136 @@ +# 快速入门 + +## 概述 + +本文档围绕新增文档，修改文档，删除文档三个任务场景，为开发者明确文档开发流程。开发需要具备以下经验和技能： + +- 了解 Git 基本操作 +- 了解 markdown 写作规范 +- 了解 openEuler 文档仓组织结构 + +## 新增文档 + +若开发者希望在服务器场景下新增《升级指南》，可参考以下操作步骤： + +1. 创建存放文件夹 + + 确定《升级指南》的[存放位置](./directory_structure_introductory.md#文档存放地址)，在此处新建一个文件夹，用于存放该指南下所有的`.md`文件。 + + ```text + ├─docs + | ├─en + | └─zh + | └─Server + | └─InstallationUpgrade + | ├─Installation + | └─Upgrade + | ├─openEuler_22.03_LTS_upgrade_and_downgrade.md + | └─_menu.md + ``` + +2. 生成`_menu.md`文件 + + 在步骤 1 所创建的文件夹中，新建一个`_menu.md`文件，以维护手册内各章节的展示逻辑。 + + ```yaml + --- + label: '升级指南' + ismanual: 'Y' + description: '升级 openEuler 操作系统' + children: + - label: '升降级指导' + href: './openEuler_22.03_LTS_upgrade_and_downgrade.md' + --- + ``` + +3. 关联手册至对应场景 + + 在服务器场景的 [_menu.md](https://gitee.com/openeuler/docs/blob/25.03/docs/zh/Server/_menu.md) 文件中，添加对《升级指南》的引用。 + + ```yaml + --- + label: '服务器' + children: + - label: '发行说明' + children: + - reference: './Releasenotes/Releasenotes/_menu.md' + - label: '快速入门' + children: + - reference: './Quickstart/Quickstart/_menu.md' + - label: '安装升级' + children: + - reference: './InstallationUpgrade/Installation/_menu.md' + - reference: './InstallationUpgrade/Upgrade/_menu.md' + --- + ``` + +## 修改文档 + +文档修改分为以下三种情况： + +1. 现有文档内容修改：找到文档的[存放位置](./directory_structure_introductory.md#文档存放地址)，并对其内容进行相应调整。 + +2. 手册章节目录结构调整：找到手册的`_menu.md`文件并修改。 + + 如果开发者要删除《OpenStack用户指南》中的 devstack 章节，首先要删除此章节对应的`.md`文件（[devstack.md](https://gitee.com/openeuler/openstack-docs/blob/openEuler-25.03/docs/zh/install/devstack.md)），并在《OpenStack用户指南》的 [_menu.md](https://gitee.com/openeuler/openstack-docs/blob/openEuler-25.03/docs/zh/_menu.md) 下，删除对`devstack.md`文档的引用： + + ```yaml + --- + label: 'OpenStack 用户手册' + children: + - label: '安装指导' + children: + - label: 'devstack' + href: './install/devstack.md' + - label: 'antelope'markdown + href: './install/antelope.md' + --- + ``` + +3. 手册在文档中心呈现位置修改：找到场景的`_menu.md`并修改。 + + 在服务器场景下，若开发者希望将《升级指南》调整至《安装指南》前面显示，需找到服务器场景的 [menu.md](https://gitee.com/openeuler/docs/blob/25.03/docs/zh/Server/_menu.md) 文件并加以修改： + + ```yaml + --- + label: '服务器' + children: + - label: '快速入门' + children: + - reference: './Quickstart/Quickstart/_menu.md' + - label: '安装升级' + children: + - reference: './InstallationUpgrade/Upgrade/_menu.md' + - reference: './InstallationUpgrade/Installation/_menu.md' + - label: '系统管理' + children: + - reference: './Administration/Administrator/_menu.md' + - reference: './Administration/sysMaster/_menu.md' + - reference: './Administration/CompaCommand/_menu.md' + --- + ``` + +## 删除文档 + +若开发者希望在虚拟化场景下删除《虚拟化用户指南》，可参考以下操作步骤： + +1. 首先，确定想要删除手册的[存放位置](./directory_structure_introductory.md#文档存放地址)，将其删除。 + +2. 在虚拟化场景的 [_menu.md](https://gitee.com/openeuler/docs/blob/25.03/docs/zh/Virtualization/_menu.md) 文件中，删除对《OpenStack 用户手册》的引用。 + + ```yaml + --- + label: '虚拟化' + children: + - label: '虚拟化平台' + children: + - reference: './VirtualizationPlatform/Virtualization/_menu.md' + - reference: './VirtualizationPlatform/StratoVirt/_menu.md' + --- + ``` + +## 文档暂不在文档中心发布 + +如果开发者所创作的文档内容，暂时不适合推广或尚不成熟，目前无需发布在文档中心，可在文档仓的 [archive](https://gitee.com/openeuler/docs/tree/25.03/Archive) 目录中进行增删改。等到需要发布时，再将其移至合适的目录，注意这类文档同样需要遵循写作规范。 + +> 注意：提交至 archive 目录的文档，按计划未来会发布到文档中心，若长时间无人维护，将会被清理。 diff --git a/docs/zh/contribute/directory_structure_introductory.md b/docs/zh/contribute/directory_structure_introductory.md new file mode 100644 index 0000000000000000000000000000000000000000..fa42f7d9e8477d3776fa185c915bb14e796a77a5 --- /dev/null +++ b/docs/zh/contribute/directory_structure_introductory.md @@ -0,0 +1,771 @@ +# 概述 + +## 介绍 + +openEuler的文档仓库包含 openEuler/docs 仓以及各 SIG 组的 docs 仓。基础特性文档，如发行说明、快速入门、安装、升级、管理员指南、配置与逻辑卷、配置网络、故障处理等，均在 openEuler/docs 仓集中维护。而增量特性文档，如 A-Tune 用户指南、x2openEuler 特性指南、oeAware 用户指南等，则依据特性所属的 SIG 组，分别存放在各 SIG 组的 docs 仓内。 + +如下图所示，各用户场景与工具模块的文档，由多个 SIG 组的特性文档组合而成。各 SIG 组需将各自的特性文档添加到所属场景的配置文件中，这些配置文件统一存于 openEuler/docs 仓，由 DOC SIG 负责维护。例如，A-Tune SIG 组维护 oeAware 特性文档，需要将其添加在服务器场景的配置文件中，DOC SIG 作审视；Migration SIG 组维护 x2openEuler 特性文档，需要修改服务器场景和社区工具的配置文件，因为 x2openEuler 特性文档在服务器场景和社区工具模块下均有入口。 + +![image](figures/文档仓总览.png) + +在文档仓中，docs 目录下的内容会展示于官网，其下设有 zh 和 en 两个子目录，分别用以存放中文文档与英文文档，文档目录结构严格参照官网呈现的目录层级规划设置。此外，文档仓还设有archive目录，用来存放暂不适合推广，或尚不成熟的文档。待文档完善且满足发布需求时，再将其移至 docs 目录，以便在官网展示。 + +```text +├─archive +├─docs +│ ├─en +│ └─zh +``` + +## 文档存放地址 + +### 服务器 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
场景类别手册存放地址
服务器发行说明发行说明docs/zh/Server/Releasenotes/Releasenotes
快速入门快速入门docs/zh/Server/Quickstart/Quickstart
安装升级安装指南docs/zh/Server/InstallationUpgrade/Installation
升级指南docs/zh/Server/InstallationUpgrade/Upgrade
系统管理管理员指南docs/zh/Server/Administration/Administrator
sysMaster用户指南docs/zh/Server/Administration/sysMaster
兼容性命令docs/zh/Server/Administration/CompaCommand
系统运维A-Ops用户指南docs/zh/Server/Maintenance/A-Ops
gala用户指南docs/zh/Server/Maintenance/Gala
sysmonitor用户指南docs/zh/Server/Maintenance/sysmonitor
内核热升级指南docs/zh/Server/Maintenance/KernelLiveUpgrade
SysCare用户指南docs/zh/Server/Maintenance/SysCare
常用技能docs/zh/Server/Maintenance/CommonSkills
常用定位定界工具docs/zh/Server/Maintenance/CommonTools
故障应急处理docs/zh/Server/Maintenance/Troubleshooting
安全安全加固指南docs/zh/Server/Security/SecHarden
可信计算docs/zh/Server/Security/TrustedComputing
secGear开发指南docs/zh/Server/Security/secGear
CVE-ease设计指南docs/zh/Server/Security/CVE-ease
证书签名docs/zh/Server/Security/CertSignature
SBOM用户指南docs/zh/Server/Security/Sbom
国密docs/zh/Server/Security/ShangMi
内存与存储配置和管理逻辑卷docs/zh/Server/MemoryandStorage/lvm
etmem用户指南docs/zh/Server/MemoryandStorage/etmem
GMEM用户指南docs/zh/Server/MemoryandStorage/GMEM
HSAK开发指南docs/zh/Server/MemoryandStorage/HSAK
网络配置网络docs/zh/Server/Network/NetworConfig
Gazelle用户指南docs/zh/Server/Network/Gazelle
性能调优系统资源与性能docs/zh/Server/Performance/Overall/systemResource
oeAware用户指南docs/zh/Server/Performance/TuningFramework/oeAware
sysBoost用户指南docs/zh/Server/Performance/CPUOptimization/sysBoost
使用KAE加速引擎docs/zh/Server/Performance/CPUOptimization/KAE
A-Tune用户指南docs/zh/Server/Performance/SystemOptimization/A-Tune
应用开发应用开发指南docs/zh/Server/Development/ApplicationDev
GCC用户指南docs/zh/Server/Development/GCC
HA高可用HA用户指南docs/zh/Server/HighAvailability/HA
多样性算力直连聚合用户指南docs/zh/Server/DiversifiedComputing/DPUOffload
DPU-OSdocs/zh/Server/DiversifiedComputing/DPU-OS
+ +### 虚拟化 + + + + + + + + + + + + + + + + + + + + + + +
场景类别手册存放地址
虚拟化虚拟化平台虚拟化用户指南docs/zh/Virtualization/VirtualizationPlatform/Virtualization
StratoVirt用户指南docs/zh/Virtualization/VirtualizationPlatform/StratoVirt
OpenStack用户手册openstack-docs/docs/zh
+ +### 云原生 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
场景类别手册存放地址
云原生容器引擎iSula容器引擎docs/zh/Cloud/ContainerEngine/iSulaContainerEngine
Docker容器docs/zh/Cloud/ContainerEngine/DockerEngine
容器形态安全容器docs/zh/Cloud/ContainerForm/SecureContainer
系统容器docs/zh/Cloud/ContainerForm/SystemContainer
容器运行时Kuasar多沙箱容器运行时docs/zh/Cloud/ContainerRuntime/Kuasar
容器镜像构建工具容器镜像构建docs/zh/Cloud/ImageBuilder/isula-build
云原生操作系统容器OS升级用户指南docs/zh/Cloud/KubeOS/KubeOS
云底座操作系统NestOS用户指南docs/zh/Cloud/NestOS/NestOS
混合部署云原生混合部署rubik用户指南docs/zh/Cloud/HybridDeployment/rubik
oncn-bwm用户指南docs/zh/Cloud/HybridDeployment/oncn-bwm
集群部署Kubernetes集群部署指南docs/zh/Cloud/ClusterDeployment/Kubernetes
iSulad+k8s集群部署指南docs/zh/Cloud/ClusterDeployment/iSulad+k8s
服务网格Kmesh用户指南docs/zh/Cloud/Kmesh/Kmesh
+ +### 边缘计算 + + + + + + + + + + + + + + + + + + +
场景类别手册存放地址
边缘计算 / KubeEdge部署指南docs/zh/EdgeComputing/KubeEdge
K3s部署指南docs/zh/EdgeComputing/K3s
+ +### 嵌入式 + + + + + + + + + + + + + + + + + + +
场景类别手册存放地址
嵌入式 / openEuler Embedded用户指南yocto-meta-openeuler/docs
UniProton用户指南docs/zh/Embedded/UniProton
+ +### 工具 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
工具模块类别手册存放地址
社区工具镜像构建isocut使用指南docs/zh/Tools/CommunityTools/ImageCustom/isocut
imageTailor使用指南docs/zh/Tools/CommunityTools/ImageCustom/imageTailor
编译GCC用户指南docs/zh/Server/Development/GCC
性能优化A-Tune用户指南docs/zh/Server/Performance/SystemOptimization/A-Tune
oeAware用户指南docs/zh/Server/Performance/TuningFramework/oeAware
迁移Migration-tools用户指南docs/zh/Tools/CommunityTools/Migration/migration-tools
虚拟化EulerLauncher用户指南docs/zh/Tools/CommunityTools/Virtualization/EulerLauncher
epkg软件包epkg包管理器使用指南docs/zh/Tools/CommunityTools/epkg
autopkg用户指南docs/zh/Tools/CommunityTools/epkg/autopkg
社区服务源码管理patch-trackingdocs/zh/Tools/DevOps/CodeManage/patch-tracking
包管理pkgshipdocs/zh/Tools/DevOps/packageManage/pkgship
AI / openEuler Copilot Systemdocs/zh/Tools/AI/openEuler_Copilot_System
AI大模型服务镜像使用指南docs/zh/Tools/AI/AI_Large_Model_Service_Images_Userguide
AI容器镜像用户指南docs/zh/Tools/AI/AI_Container_Image_Userguide
图形桌面使用 / Gnome用户指南docs/zh/Tools/desktop/Gnome
UKUI用户指南docs/zh/Tools/desktop/UKUI
DDE用户指南docs/zh/Tools/desktop/DDE
Kiran用户指南docs/zh/Tools/desktop/Kiran
XFCE用户指南docs/zh/Tools/desktop/XFCE
云原生工具 / CTinspector用户指南docs/zh/Tools/Cloud/CTinspector
CPDS用户指南docs/zh/Tools/Cloud/CPDS
PilotGo用户指南docs/zh/Tools/Cloud/PilotGo
系统运维热补丁制作SysCare用户指南docs/zh/Server/Maintenance/SysCare
系统监控sysmonitor用户指南docs/zh/Server/Maintenance/sysmonitor
安全 / secGear开发指南docs/zh/Server/Security/secGear
+ +## 文档仓目录结构说明 + +### 场景 + +文档中心有五个业务场景，服务器、虚拟化、云原生、边缘计算和嵌入式，分别对应 docs 仓内 docs/zh 目录下的 Server、Virtualization、Cloud、EdgeComputing 和 Embedded 子目录，工具模块对应 Tools 子目录。 + +文档仓场景相关目录结构示例如下： + +```text +├─Archive +├─docs +│ ├─en +│ └─zh +│ ├─Cloud +│ ├─EdgeComputing +│ ├─Embedded +│ ├─Server +│ ├─Tools +│ └─Virtualization +``` + +工具模块下的子模块包括社区工具、DevOps、AI、图形桌面使用、云原生工具、系统运维和安全，分别对应 Tools 目录下的 CommunityTools、DevOps、AI、desktop、Cloud、Maintenance 和 Security 子目录。 + +文档仓工具相关目录结构示例如下： + +```text +├─docs +│ ├─en +│ └─zh +│ ├─Cloud +│ ├─EdgeComputing +│ ├─Embedded +│ ├─Server +│ ├─Tools +│ │ ├─AI +│ │ ├─Cloud +│ │ ├─CommunityTools +│ │ ├─desktop +│ │ ├─DevOps +│ │ ├─Maintenance +│ │ └─Security +│ └─Virtualization +``` + +### 类别 + +各业务场景下均有具体的类别划分。就服务器场景而言，其进一步细分为发行说明、快速入门、安装升级、系统管理、系统运维等子类别。 + +文档仓服务器场景目录结构示例如下： + +```text +├─docs +│ ├─en +│ └─zh +│ ├─Cloud +│ ├─EdgeComputing +│ ├─Embedded +│ ├─Server +│ │ ├─Administration +│ │ ├─Development +│ │ ├─DiversifiedComputing +│ │ ├─HighAvailability +│ │ ├─InstallationUpgrade +│ │ ├─Maintenance +│ │ ├─MemoryandStorage +│ │ ├─Network +│ │ ├─Performance +│ │ ├─Quickstart +│ │ ├─Releasenotes +| | ├─Security +│ │ └─_menu.md +│ ├─Tools +│ └─Virtualization +``` + +### 手册 + +每个类别下存放手册或继续设置二级目录。以服务器场景中的系统运维类别为例，其中包含八本手册，每本手册分别对应文档仓的一个文件夹。 + +文档仓服务器下系统运维的目录结构示例如下： + +```text +├─docs +│ ├─en +│ └─zh +│ ├─Cloud +│ ├─EdgeComputing +│ ├─Embedded +│ ├─Server +│ │ ├─Administration +│ │ ├─Development +│ │ ├─DiversifiedComputing +│ │ ├─HighAvailability +│ │ ├─InstallationUpgrade +│ │ ├─Maintenance +│ │ │ ├─A-Ops +│ │ │ ├─CommonSkills +│ │ │ ├─CommonTools +│ │ │ ├─Gala +│ │ │ ├─KernelLiveUpgrade +│ │ │ ├─SysCare +│ │ │ ├─sysmonitor +│ │ │ └─Troubleshooting +│ │ ├─MemoryandStorage +│ │ ├─Network +│ │ ├─Performance +│ │ ├─Quickstart +│ │ ├─Releasenotes +| | ├─Security +│ │ └─_menu.md +│ ├─Tools +│ └─Virtualization +``` + +以服务器场景中的性能调优类别为例，其下进一步划分出二级目录，分别为概述、CPU调优、系统调优、调优框架。 + +文档仓服务器下性能调优的目录结构示例如下： + +```text +├─docs +│ ├─en +│ └─zh +│ ├─Cloud +│ ├─EdgeComputing +│ ├─Embedded +│ ├─Server +│ │ ├─Administration +│ │ ├─Development +│ │ ├─DiversifiedComputing +│ │ ├─HighAvailability +│ │ ├─InstallationUpgrade +│ │ ├─MemoryandStorage +│ │ ├─Network +│ │ ├─Performance +│ │ │ ├─CPUOptimization +│ │ │ │ ├─KAE +│ │ │ │ └─sysBoost +│ │ │ ├─Overall +│ │ │ │ └─systemResource +│ │ │ ├─SystemOptimization +│ │ │ │ └─A-Tune +│ │ │ └─TuningFramework +│ │ │ └─oeAware +│ │ ├─Quickstart +│ │ ├─Releasenotes +| | ├─Security +│ │ └─_menu.md +│ ├─Tools +│ └─Virtualization +``` + +每本手册包含一个或多个`.md`文件及一个`_menu.md`文件。例如，《内核热升级指南》手册中包括三篇文档，包括安装与部署、使用方法、常用问题与解决办法。 + +```text +├─docs +│ ├─en +│ └─zh +│ ├─Cloud +│ ├─EdgeComputing +│ ├─Embedded +│ ├─Server +│ │ ├─Administration +│ │ ├─Development +│ │ ├─DiversifiedComputing +│ │ ├─HighAvailability +│ │ ├─InstallationUpgrade +│ │ ├─Maintenance +│ │ │ ├─A-Ops +│ │ │ ├─CommonSkills +│ │ │ ├─CommonTools +│ │ │ ├─Gala +│ │ │ ├─KernelLiveUpgrade +│ | │ │ ├─installation-and-deployment.md +│ | │ │ ├─how-to-run.md +│ | │ │ ├─common-problems-and-solutions.md +│ | │ │ └─_menu.md +│ │ │ ├─SysCare +│ │ │ ├─sysmonitor +│ │ │ └─Troubleshooting +│ │ ├─MemoryandStorage +│ │ ├─Network +│ │ ├─Performance +│ │ ├─Quickstart +│ │ ├─Releasenotes +| | ├─Security +│ │ └─_menu.md +│ ├─Tools +│ └─Virtualization +``` + +## _menu 文件格式 + +### 手册的 _menu 文件 + +每本手册都需要维护一个`_menu.md`配置文件来维护该本手册中各章节间的逻辑关系。 + +《内核热升级指南》手册的`_menu.md`文件示例如下： + +```yaml +--- +label: '内核热升级指南' +description: '使用用户态自动化工具快速重启内核和程序热迁移实现内核热替换特性' +children: + - label: '安装与部署' + href: './installation-and-deployment.md' + - label: '使用方法' + href: './how-to-run.md' + - label: '常见问题与解决方法' + href: './common-problems-and-solutions.md' +--- +``` + +- 顶层 label 指定手册名为“内核热升级指南”。 +- description 指定该手册的简介说明。 +- children 下配置手册中的文档信息： + - children 下的 label 指定文档名称。 + - children 下的 href 指定文档地址（建议使用相对路径）。 + +### 场景的 _menu 文件 + +不仅每本手册需维护对应的`_menu.md`文件，各业务场景目录下同样要维护`_menu.md`文件。以服务器场景为例，其`_menu.md`文件示例如下： + +```yaml +--- +label: '服务器' +children: + - label: '发行说明' + children: + - reference: './Releasenotes/Releasenotes/_menu.md' + - label: '快速入门' + children: + - reference: './Quickstart/Quickstart/_menu.md' + - label: '安装升级' + children: + - reference: './InstallationUpgrade/Installation/_menu.md' + - reference: './InstallationUpgrade/Upgrade/_menu.md' + - label: '系统管理' + children: + - reference: './Administration/Administrator/_menu.md' + - reference: './Administration/sysMaster/_menu.md' + - reference: './Administration/CompaCommand/_menu.md' + - label: '系统运维' + children: + - reference: './Maintenance/A-Ops/_menu.md' + - reference: './Maintenance/Gala/_menu.md' + - reference: './Maintenance/sysmonitor/_menu.md' + - reference: './Maintenance/KernelLiveUpgrade/_menu.md' + - reference: './Maintenance/SysCare/_menu.md' + - reference: './Maintenance/CommonSkills/_menu.md' + - reference: './Maintenance/CommonTools/_menu.md' + - reference: './Maintenance/Troubleshooting/_menu.md' + - label: '安全' + children: + - reference: './Security/SecHarden/_menu.md' + - reference: './Security/TrustedComputing/_menu.md' + - reference: './Security/secGear/_menu.md' + - reference: './Security/CVE-ease/_menu.md' + - reference: './Security/CertSignature/_menu.md' + - reference: './Security/Sbom/_menu.md' + - reference: './Security/ShangMi/_menu.md' + - label: '内存与存储' + children: + - reference: './MemoryandStorage/lvm/_menu.md' + - reference: './MemoryandStorage/etmem/_menu.md' + - reference: './MemoryandStorage/GMEM/_menu.md' + - reference: './MemoryandStorage/HSAK/_menu.md' + - label: '网络' + children: + - reference: './Network/NetworConfig/_menu.md' + - reference: './Network/Gazelle/_menu.md' + - label: '性能调优' + children: + - label: '概述' + children: + - reference: './systemResource/_menu.md' + - label: '调优框架' + children: + - reference: './oeAware/_menu.md' + - label: 'CPU调优' + children: + - reference: './sysBoost/_menu.md' + - reference: './KAE/_menu.md' + - label: '系统调优' + children: + - reference: './A-Tune/_menu.md' + - label: '应用开发' + children: + - reference: './Development/ApplicationDev/_menu.md' + - reference: './Development/GCC/_menu.md' + - label: 'HA高可用' + children: + - reference: './HighAvailability/HA/_menu.md' + - label: '多样性算力' + children: + - reference: './DiversifiedComputing/DPUOffload/_menu.md' + - reference: './DiversifiedComputing/DPU-OS/_menu.md' +--- +``` + +- 顶层 label 指定场景名，例子中展示的是服务器场景。 +- 服务器 children 下的 label 对应服务器场景下的一级目录，如发行说明、快速入门、安装升级、系统管理等。 +- 每个一级目录 children 下的 reference 表明引用，您可以使用该字段引用该目录下各本手册的`_menu.md`文件或二级目录，从而形成一个完整的“菜单树”。 diff --git a/docs/zh/contribute/documentation_writing_specifications.md b/docs/zh/contribute/documentation_writing_specifications.md new file mode 100644 index 0000000000000000000000000000000000000000..63c2911f58fcdcd22ef22d7039af73b8f46b1f2b --- /dev/null +++ b/docs/zh/contribute/documentation_writing_specifications.md @@ -0,0 +1,329 @@ +# 写作规范 + +## 文档结构 + +特性手册内容一般包括概述、背景介绍、操作类文档（安装与部署、使用指南）、常见问题和附录，开发者可以根据项目实际情况增加或删减。 +以[A-Tune 项目为例](https://docs.openeuler.org/zh/docs/22.03_LTS_SP2/docs/A-Tune/A-Tune.html),可以参考如下内容： + +### 概述 + +一句话介绍特性定义与功能。 + +【举例】 + +```markdown +本文档介绍openEuler系统性能自优化软件A-Tune的安装部署和使用方法，以指导开发者快速了解并使用A-Tune。 +``` + +### 背景介绍 + +背景介绍类文档写明特性背景与简介、架构说明等。常见文档标题:`认识xxx`。 + +### 操作类文档 + +操作类文档写明步骤、注意事项、前提条件等，以便能对其他开发者起到帮助。 + +- 使用说明 + +说明此操作在什么场景下使用可以解决开发者的什么问题。 + +- 环境要求 + +执行此操作需要准备的软硬件环境、权限以及其它约束条件。 + +- 操作步骤 + +具体的操作步骤，需要注意如下事项: + - 建议一步一个操作步骤，不建议多个操作步骤合并在一个步骤中描写。 + - 如果操作可选，要明确可选条件。 + - 开发步骤中，涉及调用接口（例如使用了工具或者 SQL 语句），需要对使用的接口进行说明。 + +- 结果验证 + +说明如何验证操作结果正确。如果验证操作与步骤强相关，可以在步骤中描述。例如，执行 SQL 语句的返回信息。 + +### 常见问题 + +此类文档应该包括问题描述、产生原因及解决办法。 + +### 附录 + +附录可包含术语与缩略语介绍。 + +## 内容元素 + +### 命名 + +对于新增文档，请在对应的文件目录下新增 MarkDown 文档（即以 .md 结尾的文件）。 + +【规则】新增文档名称不能与已有文档重名，如果有请重新命名。 + +【规则】文档需要以**英文**命名。 + +【规则】文件名中不能包含括号，会导致文件目录无法正常显示。可以将括号修改为可识别的下划线（\_）或者中划线（-）。 + +【举例】 + +```text +installation_and_deployment.md #新增‘安装与部署’文档 +``` + +### 标题 + +【规则】标题尽量采用简洁的语句概况反映章节的中心内容，注意不要省略必要的信息。 + +【规则】操作类文档标题尽量用动宾结构（例如：申请权限）；相同级别，相同类型的标题结构保持一致。 + +【规则】标题不使用标点符号结尾，标题中尽量采用圆括号来表示补充说明，标题中不能出现特殊字符，如“？”。 + +【规则】标题与正文使用 1 整行换行隔开。 + +【规则】标题使用 “#” 空格连接标题名，标题级别一次只能增加一个级别且第一个标题应该是顶层标题。 + +【举例】 + +```markdown +# 一级标题 +## 二级标题 +### 三级标题 +#### 四级标题 +##### 五级标题 +###### 六级标题 +``` + +### 正文 + +【使用方法】 + +- 斜体：使用一个星号（\*）表示斜体。 + + ```txt + *斜体文本* + ``` + +- 粗体：使用两个星号（\*\*）表示粗体。 + + ```txt + **粗体文本** + ``` + +- 粗斜体：使用3个星号（\*\*\*）表示粗斜体。 + + ```txt + ***粗斜体文本*** + ``` + +- 转义：对特定内容使用转义符 \。 + + ```txt + \<转义的标记符号> + ``` + +【规则】该转义的字符必须严格用转义符 \ 。 + +【规则】如果有连续两个转义符，转义符之间要有空格 \{ \}。 + +【规则】国际化：需同时提供中英文文档，可联系或协助翻译；如需参与英文文档贡献，可参考[指南](./english_doc_contribute.md)。 + +### 空格 + +【规则】编辑文档时中文和英文之间**建议**加空格，页面展示更美观,请保持全文一致。如果是产品名词如 “豆瓣FM”，请按照官方定义格式书写。 + + 例如：openEuler 是一款开源操作系统。当前 openEuler 内核源于 Linux ，支持鲲鹏及其它多种处理器。 + +【规则】中文和数字之间加空格。 + +【规则】数字和单位之间不加空格。 + +【规则】全角标点与其他字符之间不加空格。 + + 例如：刚刚成为了 openEuler 的 maintainer，好开心。 + +### 图片 + +【使用方法】 + +```bash +![alt 属性文本](图片地址) + +![alt 属性文本](图片地址 "可选标题") +``` + +【规则】图片统一存放到文档同级目录下的 figures 文件夹中。例如，[A-Tune用户指南](https://docs.openeuler.org/zh/docs/22.03_LTS_SP2/docs/A-Tune/A-Tune.html)中的手册中使用的图片，统一存储在 [A-Tune](https://gitee.com/openeuler/docs/tree/stable2-22.03_LTS_SP2/docs/zh/docs/A-Tune/figures) 路径下。该文件夹下的文件引用图片时，使用相对引用。 + +【规则】请使用原创图片，避免存在知识产权侵权风险。 + +【规则】图文配合使用，切忌图文分离。 + +【规则】图片格式首选 png，此外也接受 jpg。图片的高不超过 640px，宽不超过 393px，图片大小建议不超过 150K。 + +【规则】中文用中文插图，英文用英文插图。 + +【规则】图片路径不能包含中文。 + +【规则】如果是截图，请在允许的范围内只保留有用的信息。图形中需要突出的关键信息，可增加红色框线或者文字备注说明。 + +【举例】 +​图片以 `![](./figures/pic_name.png)` 格式书写，“./” 不可少，否则图片无法显示到现网。 + +### 代码块 + +代码示例说明了如何实现特定功能，开发人员使用代码示例来编写和调试代码。 + +【规则】代码的逻辑和语法正确。 + +【规则】代码的输入和输出尽可能的分开。 + +【规则】保证代码中关键步骤要有注释说明。 + +【规则】文中行内代码和命令行使用 1 对反引号，如： `代码行`。 + +【规则】块级代码使用 3 个顿号或 4 个空格（不能用 TAB 键）缩进，且上下均用整行隔开。 + +【举例】 + +- 行内代码 + + ```txt + `printf()` 函数 + ``` + +- 块级代码 + + ```python + #!/usr/bin/env python3 + print("Hello, World!"); + ``` + + ```c + #include + int main(void) + { + printf("Hello world\n"); + } + ``` + +### 列表 + +- 无序列表：无序列表使用星号（**\***）、加号（**+**）或是减号（**-**）作为列表标记，这些标记后面要添加一个空格，然后再填写内容。同一个无序列表，建议使用同一个符号。 + + ```txt + * 第一项 + * 第二项 + * 第三项 + + + 第一项 + + 第二项 + + 第三项 + + + - 第一项 + - 第二项 + - 第三项 + ``` + +- 有序列表：有序列表使用数字并加上 **.** 号来表示。 + + ```txt + 1. 第一项 + 2. 第二项 + 3. 第三项 + ``` + +- 嵌套列表：列表嵌套只需在子列表中的选项前面添加四个空格即可。 + + ```txt + 1. 第一项： + - 第一项嵌套的第一个元素 + - 第一项嵌套的第二个元素 + 2. 第二项： + - 第二项嵌套的第一个元素 + - 第二项嵌套的第二个元素 + ``` + +【规则】有明显先后逻辑顺序情况请使用有序列表，并列关系、多选一情况请使用无序列表。 + +【规则】当项目列表是术语、短语时，统一不加标点符号。 + +【规则】当项目列表是句子时，统一加句号。 + +【规则】特殊情况下如果不能避免出现短语和句子混合的情况，统一加句号。 + +【规则】项目列表前几项以分号结尾，最后一项以句号结尾的形式也可以接受。 + +### 注释符号 + +文档中会出现以下注释符号，代表不同的使用场景和提示程度。如果需要提示用户注意的信息，可以根据重要程度选择对应的注释符号。 + +| 标识符 | 用途/含义 | 使用方法 | +|--------|------------------------------------------------------------------|-----------------------------------------------------------------------------| +| 警告 | 如未按该警告内容操作，可能会导致结果异常，且不可恢复。 | `>![](./public_sys-resources/icon-warning.gif)**警告：**`
`>正文内容` | +| 注意 | 如未按该注意事项操作，可能会导致任务中断或结果异常，但是可恢复。 | `>![](./public_sys-resources/icon-notice.gif)**注意：**`
`>正文内容` | +| 说明 | 提供帮助提示或有用的参考信息 | `>![](./public_sys-resources/icon-note.gif)**说明：**`
`>正文内容` | + +### 链接 + +【规则】链接需要确保指向的目标文件存在，否则会造成链接跳转不正常，不建议使用 HTML 的链接样式。 + +【举例】 + +```markdown +- 网站链接 +这是一个链接 [菜鸟教程](https://www.runoob.com)。 + +- 相对路径 + [文档开发流水线门禁](./ci_rules.md) +``` + +### 表格 + +【规则】markdown 文档中请使用以下方式创建表格，不建议使用 HTML 的表格样式。 + +【举例】 + +| 表头1 | 表头2 | +| ---------- | -------- | +| 单元格1 | 单元格2 | +| 单元格4 | 单元格4 | + +【使用方法】 +设置表格的对齐方式： + +- -: 设置内容和标题栏居右对齐。 +- :- 设置内容和标题栏居左对齐。 +- :-: 设置内容和标题栏居中对齐。 + +【规则】当表格内一列全部是术语、短语时，统一不加标点符号。 + +【规则】当表格内一列全部是句子时，统一加句号。 + +【规则】特殊情况下如果不能避免出现短语和句子混合的情况，统一加句号。 + +### 标点符号 + +【规则】单位与数字之间不建议加空格，比如 50m，10kg，64Kbit/s。 + +【规则】对于有序/无序列表，如果是长句子，建议统一以句号结尾，如果是短语，结尾可不用标点。**重点是前后一致，要么都加，要么都不加**。 + +【规则】中文文档使用全角标点。 + +【规则】数字使用半角字符。 + +【规则】感叹号使用场景为可能引发严重后果的操作或设备安全、人身安全的警告。其他场景不允许使用感叹号。 + +【规则】文内引用其他文档件事添加书名号，同时建议增加引用文档的跳转链接。例如：安装 openEuler 系统，安装方法参考《[openEuler 22.03 LTS SP2 安装指南](https://docs.openeuler.org/zh/docs/22.03_LTS_SP2/docs/Installation/installation.html)》。 + +## 语言风格 + +【规则】提交内容必须是与 openEuler 特性相关内容。 + +【规则】内容不能包含敏感信息、有强烈的种族歧视或性别歧视的内容。 + +【规则】提交的内容必须是原创内容，不得侵犯他人知识产权。 + +【规则】提交的内容必须客观、真实，不允许使用夸大宣传等词汇。 + +**文档贡献中不受欢迎的行为** + +短时间内通过自动化工具，提交大量的PR，提交大量的处理诸如拼写错误，语法错误，日期错误，语句不通顺等“无害的错误”的修正。 +具体内容以及处理措施详见 [openEuler社区开发行为规范 V1.0](https://gitee.com/openeuler/community/blob/master/zh/technical-committee/governance/openEuler%E7%A4%BE%E5%8C%BA%E5%BC%80%E5%8F%91%E8%A1%8C%E4%B8%BA%E8%A7%84%E8%8C%83.md)。 diff --git a/docs/zh/contribute/english_doc_contribute.md b/docs/zh/contribute/english_doc_contribute.md new file mode 100644 index 0000000000000000000000000000000000000000..c2afff6d143cdd6e99dd4ec82d723870fbc99cf6 --- /dev/null +++ b/docs/zh/contribute/english_doc_contribute.md @@ -0,0 +1,97 @@ +# 英文文档贡献指导 + +## 概述 + +本文旨在指导英文开发者贡献英文文档，相关规范与中文类似，均可参考[文档贡献流程](./contribution_process.md)，[文档仓库目录结构说明](./directory_structure_introductory.md)，[menu文件写作规范](./menu_specifications.md)。 + +## 英文文档目录结构 + +在 openEuler/docs 仓和 openEuler/SIG组名-docs 仓中，docs 目录下的 en 子目录，用于存放英文文档。docs/en 子目录下的目录结构与 docs/zh 子目录下目录结构相同： + +docs/en下目录结构示例如下： + +```text +├─docs +│ ├─en +│ └─zh +│ ├─Cloud +│ ├─EdgeComputing +│ ├─Embedded +│ ├─Server +│ │ ├─Administration +│ │ ├─Development +│ │ ├─DiversifiedComputing +│ │ ├─HighAvailability +│ │ ├─InstallationUpgrade +│ │ ├─Maintenance +│ │ │ ├─A-Ops +│ │ │ ├─CommonSkills +│ │ │ ├─CommonTools +│ │ │ ├─Gala +│ │ │ ├─KernelLiveUpgrade +│ │ │ ├─SysCare +│ │ │ ├─sysmonitor +│ │ │ └─Troubleshooting +│ │ ├─MemoryandStorage +│ │ ├─Network +│ │ ├─Performance +│ │ │ ├─CPUOptimization +│ │ │ │ ├─KAE +│ │ │ │ └─sysBoost +│ │ │ ├─Overall +│ │ │ │ └─systemResource +│ │ │ ├─SystemOptimization +│ │ │ │ └─A-Tune +│ │ │ └─TuningFramework +│ │ │ └─oeAware +│ │ ├─Quickstart +│ │ ├─Releasenotes +| | ├─Security +│ │ └─_menu.md +│ ├─Tools +│ │ ├─AI +│ │ ├─Cloud +│ │ ├─CommunityTools +│ │ ├─desktop +│ │ ├─DevOps +│ │ ├─Maintenance +│ │ └─Security +│ └─Virtualization +``` + +以手册《Kernel Live Upgrade Guide》手册为例，该手册包括三篇文档，存放在 Server/Maintenance/KernelLiveUpgrade 目录下： + +- Installation and Deployment，对应路径 /KernelLiveUpgrade/installation-and-deployment.md +- How to Run，对应路径 /KernelLiveUpgrade/how-to-run.md +- Common Problems and Solutions，对应路径 /KernelLiveUpgrade/common-problems-and-solutions.md +- _menu.md 文件，对应路径 /KernelLiveUpgrade/_menu.md + +> 注意：在 docs 仓存放的英文文档名和对应的中文文档名要保持一致。 + +## menu文件写作规范 + +英文文档与中文文档的`_menu.md`文件在格式设定和内容编排逻辑上保持一致，但需留意，“label” 和 “description” 这两项内容需依据语言不同分别采用英文和中文填写。 + +《Kernel Live Upgrade Guide》手册的`_menu.md`文件示例如下： + +```yaml +--- +label: 'Kernel Live Upgrade Guide' +ismanual: 'Y' +description: 'Implement the kernel hot replacement feature by using user-space automation tools to quickly restart the kernel and perform program hot migration' +children: + - label: 'Installation and Deployment' + href: './installation-and-deployment.md' + - label: 'How to Run' + href: './how-to-run.md' + - label: 'Common Problems and Solutions' + href: './common-problems-and-solutions.md' +--- +``` + +- 顶层 label 指定手册名为“Kernel Live Upgrade Guide”。 +- ismanual 设为Y，标识这是一本手册。 +- description 指定该手册的简介说明。 +- children 下配置手册中的文档信息： + - children 下的 label 指定文档的英文名称。 + - children 下的 href 指定文档地址。 diff --git a/docs/zh/contribute/figures/.keep b/docs/zh/contribute/figures/.keep new file mode 100644 index 0000000000000000000000000000000000000000..e69de29bb2d1d6434b8b29ae775ad8c2e48c5391 diff --git a/docs/zh/contribute/figures/SafetyAlert.png b/docs/zh/contribute/figures/SafetyAlert.png new file mode 100644 index 0000000000000000000000000000000000000000..0f672abbd6d2bba5621632e953d423f06db72789 Binary files /dev/null and b/docs/zh/contribute/figures/SafetyAlert.png differ diff --git a/docs/zh/contribute/figures/contribution-guide-01.png b/docs/zh/contribute/figures/contribution-guide-01.png new file mode 100644 index 0000000000000000000000000000000000000000..2ad19522b9bf642d7c3a27c81a9c3154ad048b77 Binary files /dev/null and b/docs/zh/contribute/figures/contribution-guide-01.png differ diff --git a/docs/zh/contribute/figures/contribution-guide-02.png b/docs/zh/contribute/figures/contribution-guide-02.png new file mode 100644 index 0000000000000000000000000000000000000000..a9775df9ba55e3f53269f6c78f77e79c8c0accba Binary files /dev/null and b/docs/zh/contribute/figures/contribution-guide-02.png differ diff --git a/docs/zh/contribute/figures/contribution-guide-03.png b/docs/zh/contribute/figures/contribution-guide-03.png new file mode 100644 index 0000000000000000000000000000000000000000..02898d896379d795780ab3a7bd3a8c79e6e487eb Binary files /dev/null and b/docs/zh/contribute/figures/contribution-guide-03.png differ diff --git a/docs/zh/contribute/figures/contribution-guide-04.png b/docs/zh/contribute/figures/contribution-guide-04.png new file mode 100644 index 0000000000000000000000000000000000000000..93be094648fa16b428d8a039559a1f7184f07194 Binary files /dev/null and b/docs/zh/contribute/figures/contribution-guide-04.png differ diff --git a/docs/zh/contribute/figures/contribution-guide-05.png b/docs/zh/contribute/figures/contribution-guide-05.png new file mode 100644 index 0000000000000000000000000000000000000000..7bf60faa4259ff400d77adbbdc39ecb7322f90d9 Binary files /dev/null and b/docs/zh/contribute/figures/contribution-guide-05.png differ diff --git a/docs/zh/contribute/figures/contribution-guide-06.png b/docs/zh/contribute/figures/contribution-guide-06.png new file mode 100644 index 0000000000000000000000000000000000000000..c4889bdd53677788a0b64ec2c983ed8961a6f293 Binary files /dev/null and b/docs/zh/contribute/figures/contribution-guide-06.png differ diff --git a/docs/zh/contribute/figures/contribution-guide-07.png b/docs/zh/contribute/figures/contribution-guide-07.png new file mode 100644 index 0000000000000000000000000000000000000000..b9ca9e9fa8ff5872e172708569a5cd8955228962 Binary files /dev/null and b/docs/zh/contribute/figures/contribution-guide-07.png differ diff --git a/docs/zh/contribute/figures/contribution-guide-08.png b/docs/zh/contribute/figures/contribution-guide-08.png new file mode 100644 index 0000000000000000000000000000000000000000..f6c7a896888ca96333e3f4a01c933e634b1f21cc Binary files /dev/null and b/docs/zh/contribute/figures/contribution-guide-08.png differ diff --git a/docs/zh/contribute/figures/contribution-guide-09.png b/docs/zh/contribute/figures/contribution-guide-09.png new file mode 100644 index 0000000000000000000000000000000000000000..21f1fd57b726f69ac410e2aff7e3a27cb387d6b6 Binary files /dev/null and b/docs/zh/contribute/figures/contribution-guide-09.png differ diff --git a/docs/zh/contribute/figures/contribution-guide-10.png b/docs/zh/contribute/figures/contribution-guide-10.png new file mode 100644 index 0000000000000000000000000000000000000000..9fed4d0f83d628ce4ed85315503b32fac9d820d1 Binary files /dev/null and b/docs/zh/contribute/figures/contribution-guide-10.png differ diff --git a/docs/zh/contribute/figures/contribution-guide-11.png b/docs/zh/contribute/figures/contribution-guide-11.png new file mode 100644 index 0000000000000000000000000000000000000000..4f0e23e5979a3faf8d32d66238e155a70ad96e83 Binary files /dev/null and b/docs/zh/contribute/figures/contribution-guide-11.png differ diff --git a/docs/zh/contribute/figures/contribution-guide-12.png b/docs/zh/contribute/figures/contribution-guide-12.png new file mode 100644 index 0000000000000000000000000000000000000000..89f2bec0589bd42440bac3f6aed80fa95303b027 Binary files /dev/null and b/docs/zh/contribute/figures/contribution-guide-12.png differ diff --git a/docs/zh/contribute/figures/contribution-guide-13.png b/docs/zh/contribute/figures/contribution-guide-13.png new file mode 100644 index 0000000000000000000000000000000000000000..c78ce807e8f792b952d76f2623dedc1ff7644c42 Binary files /dev/null and b/docs/zh/contribute/figures/contribution-guide-13.png differ diff --git a/docs/zh/contribute/figures/contribution-guide-14.png b/docs/zh/contribute/figures/contribution-guide-14.png new file mode 100644 index 0000000000000000000000000000000000000000..543f802aaf77a0bb65b652e3085679bf2b94c3e3 Binary files /dev/null and b/docs/zh/contribute/figures/contribution-guide-14.png differ diff --git a/docs/zh/contribute/figures/contribution-guide-15.png b/docs/zh/contribute/figures/contribution-guide-15.png new file mode 100644 index 0000000000000000000000000000000000000000..f8131b37b5a2fdae87f7d1e3e9167fe4ba85afde Binary files /dev/null and b/docs/zh/contribute/figures/contribution-guide-15.png differ diff --git a/docs/zh/contribute/figures/contribution-guide-16.png b/docs/zh/contribute/figures/contribution-guide-16.png new file mode 100644 index 0000000000000000000000000000000000000000..846634a554924f23aaee75e4c5980489c6560f1b Binary files /dev/null and b/docs/zh/contribute/figures/contribution-guide-16.png differ diff --git a/docs/zh/contribute/figures/contribution-guide-17.png b/docs/zh/contribute/figures/contribution-guide-17.png new file mode 100644 index 0000000000000000000000000000000000000000..41c280e710f013e6e999a3ac75972d8cf1fd5223 Binary files /dev/null and b/docs/zh/contribute/figures/contribution-guide-17.png differ diff --git a/docs/zh/contribute/figures/contribution-guide-18.png b/docs/zh/contribute/figures/contribution-guide-18.png new file mode 100644 index 0000000000000000000000000000000000000000..e51d3f035c62a8b2858241a2ee5141f274a62c99 Binary files /dev/null and b/docs/zh/contribute/figures/contribution-guide-18.png differ diff --git a/docs/zh/contribute/figures/contribution-guide-19.png b/docs/zh/contribute/figures/contribution-guide-19.png new file mode 100644 index 0000000000000000000000000000000000000000..a915b5f2c10bd3041026f880d801abbaa2337c1b Binary files /dev/null and b/docs/zh/contribute/figures/contribution-guide-19.png differ diff --git a/docs/zh/contribute/figures/contribution-guide-20.png b/docs/zh/contribute/figures/contribution-guide-20.png new file mode 100644 index 0000000000000000000000000000000000000000..50c4232d3627ab5defd611720dcd2a041cb44de3 Binary files /dev/null and b/docs/zh/contribute/figures/contribution-guide-20.png differ diff --git a/docs/zh/contribute/figures/contribution-guide-21.png b/docs/zh/contribute/figures/contribution-guide-21.png new file mode 100644 index 0000000000000000000000000000000000000000..ec9aed28e184756a148d55ead2aee24780bf04e2 Binary files /dev/null and b/docs/zh/contribute/figures/contribution-guide-21.png differ diff --git a/docs/zh/contribute/figures/contribution-guide-22.png b/docs/zh/contribute/figures/contribution-guide-22.png new file mode 100644 index 0000000000000000000000000000000000000000..9475425420ce3ccd94f36976663a7bfc594a8ec7 Binary files /dev/null and b/docs/zh/contribute/figures/contribution-guide-22.png differ diff --git a/docs/zh/contribute/figures/contribution-guide-23.png b/docs/zh/contribute/figures/contribution-guide-23.png new file mode 100644 index 0000000000000000000000000000000000000000..97385ffda8e525b64ed1ad4c029c9c6db9c204f4 Binary files /dev/null and b/docs/zh/contribute/figures/contribution-guide-23.png differ diff --git a/docs/zh/contribute/figures/contribution-guide-24.png b/docs/zh/contribute/figures/contribution-guide-24.png new file mode 100644 index 0000000000000000000000000000000000000000..1e04cc65be7482df0ae31b04733cb2fcc8099b3b Binary files /dev/null and b/docs/zh/contribute/figures/contribution-guide-24.png differ diff --git a/docs/zh/contribute/figures/contribution-guide-25.png b/docs/zh/contribute/figures/contribution-guide-25.png new file mode 100644 index 0000000000000000000000000000000000000000..6079cb41f4ec425228cc917ae63895bb5d2a1be1 Binary files /dev/null and b/docs/zh/contribute/figures/contribution-guide-25.png differ diff --git a/docs/zh/contribute/figures/contribution-guide-26.png b/docs/zh/contribute/figures/contribution-guide-26.png new file mode 100644 index 0000000000000000000000000000000000000000..63ea42aa75ccbba99aa8a9e40a944a02294b395a Binary files /dev/null and b/docs/zh/contribute/figures/contribution-guide-26.png differ diff --git a/docs/zh/contribute/figures/contribution-guide-27.png b/docs/zh/contribute/figures/contribution-guide-27.png new file mode 100644 index 0000000000000000000000000000000000000000..fa5eeea822d4f892806e886bce391d252c593f46 Binary files /dev/null and b/docs/zh/contribute/figures/contribution-guide-27.png differ diff --git a/docs/zh/contribute/figures/contribution-guide-28.png b/docs/zh/contribute/figures/contribution-guide-28.png new file mode 100644 index 0000000000000000000000000000000000000000..fad03464ba7479339a6906e016c764e6e3722757 Binary files /dev/null and b/docs/zh/contribute/figures/contribution-guide-28.png differ diff --git a/docs/zh/contribute/figures/contribution-guide-29.png b/docs/zh/contribute/figures/contribution-guide-29.png new file mode 100644 index 0000000000000000000000000000000000000000..fe77620e2b9d79b7cb9a7df21715f515c0f82844 Binary files /dev/null and b/docs/zh/contribute/figures/contribution-guide-29.png differ diff --git a/docs/zh/contribute/figures/contribution-guide-30.png b/docs/zh/contribute/figures/contribution-guide-30.png new file mode 100644 index 0000000000000000000000000000000000000000..28721c35270222f1c3460341d0ae361469eaa524 Binary files /dev/null and b/docs/zh/contribute/figures/contribution-guide-30.png differ diff --git a/docs/zh/contribute/figures/doccenter-modules.png b/docs/zh/contribute/figures/doccenter-modules.png new file mode 100644 index 0000000000000000000000000000000000000000..307644ef6e67e75680d50d411984e891d9462120 Binary files /dev/null and b/docs/zh/contribute/figures/doccenter-modules.png differ diff --git a/docs/zh/contribute/figures/docs-server-cloud-etc.png b/docs/zh/contribute/figures/docs-server-cloud-etc.png new file mode 100644 index 0000000000000000000000000000000000000000..dc65aab430b357c988d277f842c9837ad1ff8d78 Binary files /dev/null and b/docs/zh/contribute/figures/docs-server-cloud-etc.png differ diff --git a/docs/zh/contribute/figures/docs-zh-en.png b/docs/zh/contribute/figures/docs-zh-en.png new file mode 100644 index 0000000000000000000000000000000000000000..c7ffa94f0ffaeeae49a2e16df93b9c8f2c722f4e Binary files /dev/null and b/docs/zh/contribute/figures/docs-zh-en.png differ diff --git a/docs/zh/contribute/figures/kernelliveupgrade.png b/docs/zh/contribute/figures/kernelliveupgrade.png new file mode 100644 index 0000000000000000000000000000000000000000..ce0f2f2be2d17412acd49dabe90d93f147e39f6f Binary files /dev/null and b/docs/zh/contribute/figures/kernelliveupgrade.png differ diff --git a/docs/zh/contribute/figures/maintenance-manual.png b/docs/zh/contribute/figures/maintenance-manual.png new file mode 100644 index 0000000000000000000000000000000000000000..4b434a36d5226a1e2132dabcf7ed31c592896b6f Binary files /dev/null and b/docs/zh/contribute/figures/maintenance-manual.png differ diff --git a/docs/zh/contribute/figures/openstackgitee.jpg b/docs/zh/contribute/figures/openstackgitee.jpg new file mode 100644 index 0000000000000000000000000000000000000000..abf6e87c05d355e822a004955965c4795a8651a5 Binary files /dev/null and b/docs/zh/contribute/figures/openstackgitee.jpg differ diff --git "a/docs/zh/contribute/figures/openstack\346\230\276\347\244\272.jpg" "b/docs/zh/contribute/figures/openstack\346\230\276\347\244\272.jpg" new file mode 100644 index 0000000000000000000000000000000000000000..ed1ec0c21bb5e7f23c451a942bfce5ff883bc409 Binary files /dev/null and "b/docs/zh/contribute/figures/openstack\346\230\276\347\244\272.jpg" differ diff --git a/docs/zh/contribute/figures/performance-menu.png b/docs/zh/contribute/figures/performance-menu.png new file mode 100644 index 0000000000000000000000000000000000000000..abe5f93dcf56f28e720a40a505f4245581372633 Binary files /dev/null and b/docs/zh/contribute/figures/performance-menu.png differ diff --git a/docs/zh/contribute/figures/server-admin-quickstart-etc.png b/docs/zh/contribute/figures/server-admin-quickstart-etc.png new file mode 100644 index 0000000000000000000000000000000000000000..d753a07cb9dbfc6e4cd49c5daee0aaffa3886f01 Binary files /dev/null and b/docs/zh/contribute/figures/server-admin-quickstart-etc.png differ diff --git a/docs/zh/contribute/figures/server-menu.png b/docs/zh/contribute/figures/server-menu.png new file mode 100644 index 0000000000000000000000000000000000000000..36c3e17b43f90b28fd75b118e0806e2756044051 Binary files /dev/null and b/docs/zh/contribute/figures/server-menu.png differ diff --git a/docs/zh/contribute/figures/tools-devops-ai-etc.png b/docs/zh/contribute/figures/tools-devops-ai-etc.png new file mode 100644 index 0000000000000000000000000000000000000000..3b782fe1cd2ac2c2546b86deada529d71a9f8131 Binary files /dev/null and b/docs/zh/contribute/figures/tools-devops-ai-etc.png differ diff --git "a/docs/zh/contribute/figures/\345\206\205\346\240\270\347\203\255\345\215\207\347\272\247\346\214\207\345\215\227menu.png" "b/docs/zh/contribute/figures/\345\206\205\346\240\270\347\203\255\345\215\207\347\272\247\346\214\207\345\215\227menu.png" new file mode 100644 index 0000000000000000000000000000000000000000..5c97ddadebd36e5b53be49d273623b1fd398e4ed Binary files /dev/null and "b/docs/zh/contribute/figures/\345\206\205\346\240\270\347\203\255\345\215\207\347\272\247\346\214\207\345\215\227menu.png" differ diff --git "a/docs/zh/contribute/figures/\345\215\207\347\272\247\346\214\207\345\215\227gitee.jpg" "b/docs/zh/contribute/figures/\345\215\207\347\272\247\346\214\207\345\215\227gitee.jpg" new file mode 100644 index 0000000000000000000000000000000000000000..08f908ea27faa6f49e5efa3af5c83c36ddaf175c Binary files /dev/null and "b/docs/zh/contribute/figures/\345\215\207\347\272\247\346\214\207\345\215\227gitee.jpg" differ diff --git "a/docs/zh/contribute/figures/\345\215\207\347\272\247\346\214\207\345\215\227\346\230\276\347\244\272.jpg" "b/docs/zh/contribute/figures/\345\215\207\347\272\247\346\214\207\345\215\227\346\230\276\347\244\272.jpg" new file mode 100644 index 0000000000000000000000000000000000000000..7d6514b55e0a0303c7e0fb65deaae49acd1d35aa Binary files /dev/null and "b/docs/zh/contribute/figures/\345\215\207\347\272\247\346\214\207\345\215\227\346\230\276\347\244\272.jpg" differ diff --git "a/docs/zh/contribute/figures/\345\256\211\350\243\205\345\215\207\347\272\247.jpg" "b/docs/zh/contribute/figures/\345\256\211\350\243\205\345\215\207\347\272\247.jpg" new file mode 100644 index 0000000000000000000000000000000000000000..f76220c0c4bfd59a6acff7940d756bc7f1b6d65a Binary files /dev/null and "b/docs/zh/contribute/figures/\345\256\211\350\243\205\345\215\207\347\272\247.jpg" differ diff --git "a/docs/zh/contribute/figures/\345\256\211\350\243\205\345\234\250\346\234\215\345\212\241\345\231\250.jpg" "b/docs/zh/contribute/figures/\345\256\211\350\243\205\345\234\250\346\234\215\345\212\241\345\231\250.jpg" new file mode 100644 index 0000000000000000000000000000000000000000..90977793c851947e8e3c8b1dbe7339536943adb0 Binary files /dev/null and "b/docs/zh/contribute/figures/\345\256\211\350\243\205\345\234\250\346\234\215\345\212\241\345\231\250.jpg" differ diff --git "a/docs/zh/contribute/figures/\345\256\211\350\243\205\346\214\207\345\215\227gitee.jpg" "b/docs/zh/contribute/figures/\345\256\211\350\243\205\346\214\207\345\215\227gitee.jpg" new file mode 100644 index 0000000000000000000000000000000000000000..8486eeb321335042484d96b2ad75ec6996ad4d39 Binary files /dev/null and "b/docs/zh/contribute/figures/\345\256\211\350\243\205\346\214\207\345\215\227gitee.jpg" differ diff --git "a/docs/zh/contribute/figures/\345\256\211\350\243\205\346\214\207\345\215\227\346\230\276\347\244\272.jpg" "b/docs/zh/contribute/figures/\345\256\211\350\243\205\346\214\207\345\215\227\346\230\276\347\244\272.jpg" new file mode 100644 index 0000000000000000000000000000000000000000..795048c577020455011005576fa5cc0d43af4f8c Binary files /dev/null and "b/docs/zh/contribute/figures/\345\256\211\350\243\205\346\214\207\345\215\227\346\230\276\347\244\272.jpg" differ diff --git "a/docs/zh/contribute/figures/\346\226\207\346\241\243\344\273\223\346\200\273\350\247\210.png" "b/docs/zh/contribute/figures/\346\226\207\346\241\243\344\273\223\346\200\273\350\247\210.png" new file mode 100644 index 0000000000000000000000000000000000000000..a87b2504d20c7a744421752d1e8905dc885b97b7 Binary files /dev/null and "b/docs/zh/contribute/figures/\346\226\207\346\241\243\344\273\223\346\200\273\350\247\210.png" differ diff --git a/docs/zh/contribute/markdownlint_rules.md b/docs/zh/contribute/markdownlint_rules.md new file mode 100644 index 0000000000000000000000000000000000000000..2dc12ff942b9938a545b8e8ae8693b914bfe82ea --- /dev/null +++ b/docs/zh/contribute/markdownlint_rules.md @@ -0,0 +1,903 @@ +# markdownlint 检查规则 + +本文介绍了 markdownlint v0.12.0 版本规则以及 openEuler Docs 仓的规则设置，参照依据 。对 markdownlint 规则有任何疑问或交流，请联系 ECHO[@ECHO](https://gitee.com/echo10111111)。 + +## markdownlint 介绍 + +markdownlint 是一款检查 Markdown 文件格式的工具，可以根据设置的规则对 Markdown 文件进行全面的检查。文档写作时可以借助 VSCode 等工具的 markdownlint 插件修复格式问题。 + +## 规则介绍 + +### MD001 - 标题级别一次只能增加一个级别 + +- **错误示例** + + ```text + # Header1 + + ### Header3 + ``` + +- **正确示例** + + ```text + # Header1 + + ## Header2 + + ### Header3 + + #### Header4 + ``` + +### MD002 - 第一个标题应该是顶层标题 + +- **参数** + + - `level`：指定最高级标题的级数，默认值是1。 +- **错误示例** + + ```text + ## This is not a H1 header + + ### Another header + ``` + +- **正确示例** + + ```text + # Start with a H1 header + + ## Then use a H2 for subsections + ``` + +### MD003 - 标题样式 + +- **参数** + + - `style`：指定文档标题的样式，有 `consistent`、`atx`、`atx_closed`、`setext`、`setext_with_atx`五种。本仓已设置为 `atx`。 +- **错误示例** + + ```text + # ATX style H1 + + ## Closed ATX style H2 ## + + Setext style H1 + =============== + ``` + +- **正确示例** + + ```text + # ATX style H1 + + ## ATX style H2 + ``` + +### MD004 - 无序列表样式 + +- **参数** + + - `style`：指定无序列表的样式，有 `consistent(定义时符号前后保持一致)`、`astrisk(用星号定义)`、`plus(用加号定义)`、`dash(用减号定义)`、`sublist(定义多重列表的时候用不同的符号定义)`五种，默认为 `consistent`。 +- **错误示例** + + ```text + * Item 1 + + Item 2 + ``` + +- **正确示例** + + ```text + * Item 1 + * Item 2 + ``` + +### MD005 - 同一级别的列表项缩进不一致 + +- **错误示例** + + ```text + * Item1 + * nested item 1 + * nested item 2 + * A misaligned item + ``` + +- **正确示例** + + ```text + * Item1 + * nested item 1 + * nested item 2 + * nested item 3 + ``` + +### MD006 - 一级列表不能缩进 + +- **错误示例** + + ```text + Some text + + * List item + * List item + ``` + +- **正确示例** + + ```text + Some text + + * List item + * List item + ``` + +### MD007 - 无序列表缩进 + +- **参数** + + - `ident`：指定无序列表嵌套时缩进的空格数，默认值是2。本仓将其设置为4，即需要缩进4个空格。 +- **错误示例** + + ```text + * List item + * Nested list item indented by 4 spaces + ``` + +- **正确示例** + + ```text + * List item + * Nested list item indented by 2 spaces + ``` + +### MD009 - 行尾空格 + +本仓已忽略这条规则。 + +- **参数** + - `br_spaces`：指定在行尾可以添加的空格的数目，默认值为0，空格数目建议大于等于2，如果小于2，会默认为0。 + +### MD010 - 不能使用tab键缩进，要使用空格 + +- **参数** + + - `code_blocks`：指定本条规则在代码块里是否 (true or false) 生效,默认是 true。 +- **错误示例** + + ```text + Some text + + * hard tab character used to indent the list item + ``` + +- **正确示例** + + ```text + Some text + + * Spaces used to indent the list item instead + ``` + +### MD011 - 反向链接语法 + +- **错误示例** + + ```text + (Incorrect link syntax)[http://www.example.com] + ``` + +- **正确示例** + + ```text + [Correct link syntax](http://www.example.com) + ``` + +### MD012 - 多个连续的空行 + +- **参数** + + - `maximum`：指定文档中可以连续的最多的空行数，默认值是1。 +- **错误示例** + + ```text + Some text here + + + Some more text here + ``` + +- **正确示例** + + ```text + Some text here + + Some more text here + ``` + +> 注意：如果代码块内有多个连续的空行，将不会触发此规则。 + +### MD013 - 行的长度 + +本仓已忽略这条规则。 + +- **参数** + + - `line_length`：指定行的最大长度，默认是80。 + - `heading_line_length`：指定标题行的最大的长度，默认是80。 + - `code_blocks`：指定规则是否(true or false)对代码块生效，默认是true。 + - `tables`：指定规则是否(true or false)对表格生效，默认是true。 + - `headings`：指定规则是否(true or false)对标题生效，默认是true。 + +### MD014 - 命令前使用$而不显示输出 + +本仓已忽略这条规则。 + +- **错误示例** + + ```text + sl + cat foo + less bar + ``` + +- **正确示例** + + ```text + ls + cat foo + less bar + ``` + + ```text + $ ls + foo bar + $ cat foo + Hello world + $ cat bar + baz + ``` + + 在代码块中，终端命令前不需要要有\$，但是如果代码中既有终端命令，也有命令的输出，则终端前可以有\$。 + +### MD018 - atx样式的标题后没有空格 + +- **错误示例** + + ```text + #Header1 + + ##Header2 + ``` + +- **正确示例** + + ```text + # Header1 + + ## Header2 + ``` + +### MD019 - atx样式的标题后有多个空格 + +- **错误示例** + + ```text + # Header1 + + ## Header2 + ``` + +- **正确示例** + + ```text + # Header1 + + ## Header2 + ``` + +### MD020 - closed atx样式的标题内没有空格 + +本仓已忽略这条规则。 + +- **错误示例** + + ```text + #Header1# + + ##Header2## + ``` + +- **正确示例** + + ```text + # Header1 # + + ## Header2 ## + ``` + +### MD021 - closed atx样式的标题内有多个空格 + +本仓已忽略这条规则。 + +- **错误示例** + + ```text + # Header1 # + + ## Header2 ## + ``` + +- **正确示例** + + ```text + # Header1 # + + ## Header2 ## + ``` + +### MD022 - 标题行的上下行应该都是空行 + +- **参数** + + - `lines_above`：指定标题行上方的空行数，默认值是1。 + - `lines_below`：指定标题行方的空行数，默认值是1。 +- **错误示例** + + ```text + # Header1 + Some text + + Some more text + ## Header2 + ``` + +- **正确示例** + + ```text + # Header1 + + Some text + + Some more text + + ## Header2 + ``` + +### MD023 - 标题必须从行首开始 + +- **错误示例** + + ```text + Some text + ## Indented header + ``` + +- **正确示例** + + ```text + Some text + + ## Header + ``` + +### MD024 - 不能有重复内容的标题 + +本仓已忽略这条规则。 + +- **错误示例** + + ```text + # Some text + + ## Some text + ``` + +- **正确示例** + + ```text + # Some text + + ## Some more text + ``` + +### MD025 - 文档中有多个顶级标题 + +本仓已忽略这条规则。 + +- **参数** + + - `level`：指定文档最高级的标题，默认值是1。 +- **错误示例** + + ```text + # Top level header + + # Another top level header + ``` + +- **正确示例** + + ```text + # Title + + ## Header + + ### Another header + ``` + +### MD026 - 标题行尾的标点符号 + +- **参数** + + - `punctuation`：指定标题行尾不能有的标点符号，默认值是".,;:!?"。 +- **错误示例** + + ```text + # This is a header. + ``` + +- **正确示例** + + ```text + # This is a header + ``` + +### MD027 - 块引用符号后的多个空格 + +- **错误示例** + + ```text + > This is a block quote with bad indentation + > there should only be one + ``` + +- **正确示例** + + ```text + > This is a block quote with bad indentation + > there should only be one + ``` + +### MD028 - 块引用内的空行 + +- **错误示例** + + ```text + > This is a blockquote + > which is immediately followed by + + > this blockquote. Unfortunately + > in some parsers, this are treated as the same blockquote. + ``` + +- **正确示例** + + ```text + > This is a blockquote. + > + > This is the same blockquote. + ``` + +### MD029 - 有序列表的前缀序号 + +- **参数** + + - `style`：指定前缀序号的格式，有 `one`(只用1做前缀)，`ordered`(从1开始的加1递增数字做前缀)两种，默认值是 `one`。本仓设置为`ordered`。 +- **错误示例** + + ```text + 1. Do this + 1. Do that + 1. Done + ``` + +- **正确示例** + + ```text + 1. Do this + 2. Do that + 3. Done + ``` + +### MD030 - 列表标记后的空格 + +- **参数** + + - `ul_single`：无序列表单个段落的前缀符号和文字之间的空格数，默认值是1。 + - `ol_single`：有序列表单个段落的前缀符号和文字之间的空格数，默认值是1。 + - `ul_multi`：无序列表多个段落的前缀符号和文字之间的空格数，默认值是1。 + - `ol_multi`：有序列表单个段落的前缀符号和文字之间的空格数，默认值是1。 +- **错误示例** + + ```text + * Foo + * Bar + * Baz + ``` + +- **正确示例** + + ```text + * Foo + * Bar + * Baz + ``` + +### MD031 - 单独的代码块前后需要用空格隔开（除非是在文档的开头或者结尾） + +- **错误示例** + + ````text + Some text + ``` + + Code block + + ``` + + ``` + + Another code block + + ``` + Some more text + ```` + +- **正确示例** + + ````text + Some text + + ``` + + Code block + + ``` + + ``` + + Another code block + + ``` + + Some more text + ```` + +### MD032 - 列表前后需要用空格隔开（除非是在文档的开头或者结尾） + +- **错误示例** + + ```text + Some text + * Some + * List + + 1. Some + 2. List + Some text + ``` + +- **正确示例** + + ```text + Some text + + * Some + * List + + 1. Some + 2. List + + Some text + ``` + +### MD033 - 内联HTML + +本仓已忽略这条规则。 + +- **错误示例** + + ```text +

Inline HTML header

+ ``` + +- **正确示例** + + ```text + # Markdown header + ``` + +### MD034 - 使用纯URL + +- **错误示例** + + ```text + For more information, see http://www.example.com/. + ``` + +- **正确示例** + + ```text + For more information, see . + ``` + +### MD035 - 水平线样式 + +- **参数** + + - `style`：指定创建水平线的方式，有 `consistent`、`***`、`---`或其他指定水平线的字符串，默认值是 `consistent`。 + +### MD036 - 使用强调标记代替标题 + +本仓已忽略这条规则。 + +- **参数** + + - `punctuation`：指定用于结尾的标点符号，以此符号结尾的强调不会被视为以强调代替标题，默认值是".,;:!?" +- **错误示例** + + ```text + **My document** + + Lorem ipsum dolor sit amet... + + _Another section_ + + Consectetur adipiscing elit, sed to eiusmd + ``` + +- **正确示例** + + ```text + # My document + + Lorem ipsum dolor sit amet... + + ## Another section + + Consectetur adipiscing elit, sed to eiusmd + ``` + +### MD037 - 强调标记内强调的符号和强调的文字之间不能有空格 + +- **错误示例** + + ```text + Here is some ** bold ** text + + Here is some * italic * text + + Here is some more __ bold __ text + + Here is some more _ italic _ text + ``` + +- **正确示例** + + ```text + Here is some **bold** text + + Here is some *italic* text + + Here is some more __bold__ text + + Here is some more _italic_ text + ``` + +### MD038 - 单反引号和之间的内容不能有空格 + +- **错误示例** + + ```text + ` some text ` + `some text ` + ` some text` + ``` + +- **正确示例** + + ```text + `some text` + ``` + +### MD039 - 链接文本和包围它的中括号之间内容不能有空格 + +- **错误示例** + + ```text + [ a link ](http://www.example.com/) + ``` + +- **正确示例** + + ```text + [a link](http://www.example.com/) + ``` + +### MD040 - 代码块应指定代码块的编程语言 + +- **错误示例** + + ````text + ``` + #!/bin/bash + echo Hello world + ``` + ```` + +- **正确示例** + + ````text + ```bash + #!/bin/bash + echo Hello world + ``` + ```` + +- **常用的代码块编程语音** + + | 语言支持 | 关键字 | + | ---------------- | -------- | + | Python | python | + | C | cpp | + | Java | java | + | Shell | bash | + | Markdown | markdown | + | JavaScript | js | + | CSS | css | + | SQL | sql | + | PHP | php | + | Text | text | + | XML | html | + | Bat | bat | + | Protocol Buffers | protobuf | + +### MD041 - 文件中的第一行应该是顶级标题 + +- **参数** + + - `level`：指定文档最高级的标题，默认值是1。 +- **错误示例** + + ```text + This is a file without a header + ``` + +- **正确示例** + + ```text + # File with header + + This is a file with a top level header + ``` + +### MD046 - 代码块样式 + +- **参数** + + - `style`：指定代码块定义格式，有 `fenced（使用三个反引号）`，`indented（使用缩进）`，`consistent（上下文一致）`三种，默认值是 `fenced`。 +- **错误示例** + + ```text + Some text. + + Code block + + Some more text. + ``` + +- **正确示例** + + ````text + Some text. + + ```ruby + Code block + ``` + + Some more text. + ```` + +### MD047 - 文件应以单个换行符结尾 + +- **错误示例** + + ```text + # Header + + This file ends without a newline.[EOF] + ``` + +- **正确示例** + + ````text + # Header + + This file ends with a newline. + [EOF] + ```` + +## openEuler 规则设置 + +- openEuler 规则采用如下方案： + + - MD003 (标题样式) 规则将参数 `style`设置为`atx`。 + - MD007（无序列表缩进）规则将参数 `indent`设置为4。 + - MD029（有序列表的前缀序号）规则将参数`style`设置为`ordered`。 + - 忽略 MD009（行尾空格）这条规则。 + - 忽略 MD013（行的长度）这条规则。 + - 忽略 MD014（命令前使用\$而不显示输出）这条规则。 + - 忽略 MD020（closed atx样式的标题内没有空格）这条规则。 + - 忽略 MD021（closed atx样式的标题内有多个空格）这条规则。 + - 忽略 MD024（不能有重复内容的标题）这条规则。 + - 忽略 MD025 （文档中有多个顶级标题）这条规则。 + - 忽略 MD033（内联HTML）这条规则。 + - 忽略 MD036（使用强调标记代替标题）这条规则。 + +- ruby 文件的书写方式如下： + + ```bash + all + rule 'MD003', :style => :atx + rule 'MD007', :indent => 4 + rule 'MD029', :style => :ordered + exclude_rule 'MD009' + exclude_rule 'MD013' + exclude_rule 'MD014' + exclude_rule 'MD020' + exclude_rule 'MD021' + exclude_rule 'MD024' + exclude_rule 'MD025' + exclude_rule 'MD033' + exclude_rule 'MD036' + ``` + +## VSCode 中 Markdown 插件 + +### markdownlint + +markdownlint 扩展库包含 markdown 文件规则库，以保证 Markdown 文件与其标准保持一致。添加配置后，markdownlint 可以自动检查文档错误。 + +#### 安装 + +- 按下 `Ctrl_Shift+X`以打开扩展选项卡。 +- 输入 `markdownlint` 以找到扩展。 +- 点击 `Install` 按钮，然后再点击`Enable`按钮。 + +#### 配置 + +注意：VSCode 中 markdownlint 参照的版本是 David Anson 拟定的，与 openEuler 仓使用的 markdownlint 官方 v0.12.0 版本有差异。为了与 openEuler 仓配置的规则保持一致，请参考下方配置项。 + +- 在命令面板（`Ctrl+Shift+P`）中输入`Open Settings (JSON)`命令。 +- 在 Json 对象中添加如下配置： + + ```bash + "markdownlint.config":{ + "default":true, + "MD003":{"style":"atx"}, + "MD007":{"indent":4}, + "MD029":{"style":"ordered"}, + "MD009":false, + "MD013":false, + "MD014":false, + "MD020":false, + "MD021":false, + "MD024":false, + "MD025":false, + "MD033":false, + "MD036":false, + "MD042":false, + "MD043":false, + "MD044":false, + "MD045":false, + "MD048":false, + "MD049":false, + "MD050":false, + "MD051":false, + "MD052":false, + "MD053":false + } + ``` diff --git a/docs/zh/contribute/markdownlint_tools.md b/docs/zh/contribute/markdownlint_tools.md new file mode 100644 index 0000000000000000000000000000000000000000..73ab1dd3981b4f07e61a9a28e01044508510b041 --- /dev/null +++ b/docs/zh/contribute/markdownlint_tools.md @@ -0,0 +1,66 @@ +# markdownlint 错误修复工具 + +markdownlint-cli2 适用于批量修改 markdownlint 低错问题，如空行、缩进等，大大提高文档开发效率，但是复杂问题仍需要手动修复。 + +## 安装 Node.js + npm + +进入 [Node.js](https://nodejs.org/zh-cn)官网下载 Node.js，并按照提示完成安装。 + +分别执行如下两条命令，如果显示版本号，则说明安装成功。 + +```shell +node -v +npm -v +``` + +## 安装 markdownlint-cli2 + +执行如下命令，安装 markdownlint-cli2。 + +```shell +npm install markdownlint-cli2 --global +``` + +如果遇到类似以下错误，可能权限问题导致的。 + +```txt +npm error code EACCES +npm error syscall mkdir +npm error path /usr/local/lib/node_modules/markdownlint-cli2 +npm error errno -13 +``` + +以管理员身份解决该问题：如果是 Mac 或 Linux 系统，可以在命令前加 `sudo`；如果是 `Windows` 系统，在命令提示符或者Powershell中以管理员身份运行命令。 + +## 配置 markdownlint-cli2 + +markdownlint-cli2支持指定检查项，配置文件默认名为.markdownlint.json。将配置文件与待检查的 markdown 文件放在同一文件夹（如果要检查多个文件，则放在其共同的最上级文件夹），markdownlint-cli2就会自动读取并执行。 + +./markdownlint.json 文件示例如下： + +```bash +{ + "MD003":{"style":"atx"}, + "MD007":{"indent":4}, + "MD029":{"style":"ordered"}, + "MD009":false, + "MD013":false, + "MD014":false, + "MD020":false, + "MD021":false, + "MD024":false, + "MD025":false, + "MD033":false, + "MD036":false, + "MD042":false, + "MD043":false, + "MD044":false, + "MD045":false, + "MD048":false, + "MD049":false, + "MD050":false, + "MD051":false, + "MD052":false, + "MD053":false +} +``` diff --git a/docs/zh/contribute/menu_specifications.md b/docs/zh/contribute/menu_specifications.md new file mode 100644 index 0000000000000000000000000000000000000000..6448da8f080ac98fe191a6838a23e2c3e6a569c7 --- /dev/null +++ b/docs/zh/contribute/menu_specifications.md @@ -0,0 +1,120 @@ +# menu 文件写作规范 + +## 概述 + +在文档仓中，我们有一个“菜单文件”的概念，其作用在于构建并维护文档对应的目录结构，我们将菜单文件统一命名为`_menu.md`，并在该 markdown 中使用 yaml 元数据来进行配置。针对每个场景及每本手册，我们做了拆分，每本手册维护一个独立的`_menu.md`，这样各手册之间互不干扰，且各个手册均能独立编译。 + +## 手册的 menu 文件 + +每本手册都需要维护一个`_menu.md`配置文件来维护该本手册中文档的逻辑关系。 + +《内核热升级指南》手册的`_menu.md`文件示例如下： + +```yaml +--- +label: '内核热升级指南' +description: '使用用户态自动化工具快速重启内核和程序热迁移实现内核热替换特性' +children: + - label: '安装与部署' + href: './installation-and-deployment.md' + - label: '使用方法' + href: './how-to-run.md' + - label: '常见问题与解决方法' + href: './common-problems-and-solutions.md' +--- +``` + +- 顶层 label 指定手册名为“内核热升级指南”。 +- description 指定该手册的简介说明。 +- children 下配置手册中的文档信息： + - children 下的 label 指定文档名称。 + - children 下的 href 指定文档地址（建议使用相对路径）。 + +呈现效果如下： + +![image](figures/内核热升级指南menu.png) + +## 场景的 menu 文件 + +不仅每本手册需维护对应的`_menu.md`文件，各业务场景目录下同样要维护`_menu.md`文件。以服务器场景为例，其`_menu.md`文件示例如下： + +```yaml +--- +label: '服务器' +children: + - label: '发行说明' + children: + - reference: './Releasenotes/Releasenotes/_menu.md' + - label: '快速入门' + children: + - reference: './Quickstart/Quickstart/_menu.md' + - label: '安装升级' + children: + - reference: './InstallationUpgrade/Installation/_menu.md' + - reference: './InstallationUpgrade/Upgrade/_menu.md' + - label: '系统管理' + children: + - reference: './Administration/Administrator/_menu.md' + - reference: './Administration/sysMaster/_menu.md' + - reference: './Administration/CompaCommand/_menu.md' + - label: '系统运维' + children: + - reference: './Maintenance/A-Ops/_menu.md' + - reference: './Maintenance/Gala/_menu.md' + - reference: './Maintenance/sysmonitor/_menu.md' + - reference: './Maintenance/KernelLiveUpgrade/_menu.md' + - reference: './Maintenance/SysCare/_menu.md' + - reference: './Maintenance/CommonSkills/_menu.md' + - reference: './Maintenance/CommonTools/_menu.md' + - reference: './Maintenance/Troubleshooting/_menu.md' + - label: '安全' + children: + - reference: './Security/SecHarden/_menu.md' + - reference: './Security/TrustedComputing/_menu.md' + - reference: './Security/secGear/_menu.md' + - reference: './Security/CVE-ease/_menu.md' + - reference: './Security/CertSignature/_menu.md' + - reference: './Security/Sbom/_menu.md' + - reference: './Security/ShangMi/_menu.md' + - label: '内存与存储' + children: + - reference: './MemoryandStorage/lvm/_menu.md' + - reference: './MemoryandStorage/etmem/_menu.md' + - reference: './MemoryandStorage/GMEM/_menu.md' + - reference: './MemoryandStorage/HSAK/_menu.md' + - label: '网络' + children: + - reference: './Network/NetworConfig/_menu.md' + - reference: './Network/Gazelle/_menu.md' + - label: '性能调优' + children: + - label: '概述' + children: + - reference: './systemResource/_menu.md' + - label: '调优框架' + children: + - reference: './oeAware/_menu.md' + - label: 'CPU调优' + children: + - reference: './sysBoost/_menu.md' + - reference: './KAE/_menu.md' + - label: '系统调优' + children: + - reference: './A-Tune/_menu.md' + - label: '应用开发' + children: + - reference: './Development/ApplicationDev/_menu.md' + - reference: './Development/GCC/_menu.md' + - label: 'HA高可用' + children: + - reference: './HighAvailability/HA/_menu.md' + - label: '多样性算力' + children: + - reference: './DiversifiedComputing/DPUOffload/_menu.md' + - reference: './DiversifiedComputing/DPU-OS/_menu.md' +--- +``` + +- 顶层 label 指定场景名，例子中展示的是服务器场景。 +- 服务器 children 下的 label 对应服务器场景下的一级目录，如发行说明、快速入门、安装升级、系统管理等。 +- 每个一级目录 children 下的 reference 表明引用，您可以使用该字段引用该目录下各本手册的`_menu.md`文件或二级目录，从而形成一个完整的“菜单树”。 diff --git "a/docs/zh/contribute/openEuler\345\274\200\346\272\220\347\244\276\345\214\272\350\264\241\347\214\256\346\214\207\345\215\227.md" "b/docs/zh/contribute/openEuler\345\274\200\346\272\220\347\244\276\345\214\272\350\264\241\347\214\256\346\214\207\345\215\227.md" new file mode 100644 index 0000000000000000000000000000000000000000..e2db405b65d0eea22701c7e6f73736cf74db9574 --- /dev/null +++ "b/docs/zh/contribute/openEuler\345\274\200\346\272\220\347\244\276\345\214\272\350\264\241\347\214\256\346\214\207\345\215\227.md" @@ -0,0 +1,515 @@ +# openEuler开源社区贡献指南 + +# 前言 + +openEuler 是一款由全球开源贡献者构建的高效、稳定、安全的开源操作系统。同时， openEuler 是一个面向全球的操作系统开源社区，通过社区合作，打造创新平台。本文以贡献Gitee平台上的openEuler 社区为例，为开源社区贡献者提供详细的贡献指导，从基础介绍到网页操作到工具使用再到贡献流程，全方位推动开源社区繁荣。 + +# 开源基础 + +## 初识开源社区 + +### 介绍 + +开源即开放源代码（Open Source Code），也称为源代码公开，指的是一种软件发布模式。开源社区又称开放源代码社区（Open Source Code Community or Open Source Community），一般由拥有共同兴趣爱好的人所组成，根据相应的开源软件许可证协议公布软件源代码的网络平台，同时也为网络成员提供一个自由学习交流的空间。从一定程度上讲，开源社区与开源产品的边界较为模糊，如Linux既指开源社区，由参与者共同管理，同时又指一套性能稳健的操作系统，其内核（Linux kernel）成为许多派生操作系统如Ubuntu的搭建基础。（百度百科） +开源社区发展迅速，贡献者遍布全球且呈高速增长之势。据全球最大开源项目托管平台 GitHub 统计，2020年较上一年新增了1600万开发者用户，预计2025年开发者用户的数量将达到1亿。这其中，在 GitHub 的中国开发者数量及开源贡献度增长已成为全球最快。GitHub 预测到2030年中国开发者将成为全球最大的开源群体。（电子信息产业网） + +### 主流开源社区 + +| 名称 | 简述 | 网址 | +| :------------ | :----------------------------------------------------------- | :----------------------------------------------------------- | +| Linux内核社区 | 由全球不同地方的开发人员组成，它以代码、风格、开发流程的高质量标准著称。 | [https://www.kernel.org/](https://www.kernel.org/) | +| Alpha | Alpha处理器在Linux领域中很受欢迎，尤其用以处理高性能计算。 | [https://www.alpha.org/](https://www.alpha.org/) | +| PowerPC | 提供对使用PowerPC微处理器的Mac计算机的支持，同时也会支持一些IBM的系统。 | [https://www.powerprogress.org/en/](https://www.powerprogress.org/en/) | +| Apache | 以讨论Linux/Unix类操作系统技术、软件开发技术、数据库技术和网络应用技术等为主的开源技术社区网站。其宗旨是给所有爱好Linux/Unix技术、开源技术的朋友提供一个自由、开放、免费的交流空间。 | [https://community.apache.org/](https://community.apache.org/) | +| SourceForge | SourceForge.net (SF.net)是开源软件的开发者进行开发管理的集中式场所，也是全球最大开源软件开发平台和仓库，由VA Software提供主机，并运行SourceForge软件。 | [https://sourceforge.net/](https://sourceforge.net/) | +| Google Source | 谷歌的android代码开源网站，包含了谷歌的各代nexus的源码，这些源码都是跟随android的版本演进。 | [https://android.googlesource.com](https://android.googlesource.com); [https://github.com/android/](https://github.com/android/) | + +### 开源社区的角色 + +>![image](figures/contribution-guide-01.png) + +### 贡献开源的意义 + +**巩固现有技能**：无论是撰写代码、设计用户界面、图形设计、撰写文档、亦或是组织活动，假如你有实践的愿望，你总能在开源项目中找到自己的位置。 +**建立声誉（职业口碑）**：由于开源下所有工作都是公开的，开源项目会是一个很好展示你实力的地方。 +**遇见知己**：开源项目一般都会有一个和谐、热心的社区。很多人便是通过技术研讨会亦或是聊天室的深入探讨建立起深厚友谊。 +**学习领导和管理的艺术**：开源为实践领导力和管理技能提供了很好的机会，比如解决冲突、组织团队、工作的优先级排列。 +**寻找导师/帮助他人**：和他人在一个共享的项目下工作，这意味着需要向他人解释清楚自己是如何做的，同理，也需要向他人求助，询问别人是如何做的。相互学习和彼此教学对于每位参与者都能满载而归。 +**鼓励做出改变**：在开源的世界里，贡献者不一定非得是拥有大量经验的人。在开源的项目中，没有那么多的顾忌，你只需要做就可以了，哪怕只是纠正网站一个小小的拼写错误。开源让人们在很舒服的状态做事，而这才是这个世界应有的体验。(开源社) + +### 开源软件许可证协议 + +开源许可协议（License）是指开源社区为了维护作者和贡献者的合法权利，保证软件不被一些商业机构或个人窃取，影响软件的发展而开发的协议。License的条款由权利、义务、限制三种组成： +● 权利：你可以使用该软件做什么事情 +● 义务：你使用这个软件时必须履行什么样的义务 +● 限制：你不能够做什么事情 +开源许可证是一类组合。对于大部分开源许可证，权利（红框）均授予，著作权人几乎不承担任何义务（蓝框），只是被授权人承担的义务又较多不同（绿框）。 (License遵从性指导书) +![iamge](figures/contribution-guide-02.png) + +以下为openEuler docs SIG的许可证实例： +![image](figures/contribution-guide-03.png) + +## 初识openEuler + +### 介绍 + +openEuler 是一个开源、免费的 Linux 发行版平台，通过开放的社区形式与全球的开发者共同构建一个开放、多元和架构包容的软件生态体系。同时，openEuler也是一个创新平台，鼓励任何人在该平台上提出新想法、开拓新思路、实践新方案。 +openEuler的愿景是：通过社区合作，打造创新平台，构建支持多处理器架构、统一和开放的操作系统openEuler，推动软硬件生态繁荣发展。 + +### openEuler组织架构 + +![image](figures/contribution-guide-04.png) + +### openEuler贡献流程 + +![image](figures/contribution-guide-05.png) + +（openEuler官网） + +# Gitee基础 + +Gitee 是开源中国社区2013年推出的基于 Git 的代码托管服务，目前已经成为国内知名的代码托管平台，致力于为国内开发者提供优质稳定的托管服务。Gitee 除了提供最基础的Git代码托管之外，还提供代码在线查看、历史版本查看、Fork、Pull Request（PR）、打包下载任意版本、Issue、Wiki 、保护分支、代码质量检测、PaaS项目演示等方便管理、开发、协作、共享的功能。本章介绍Gitee贡献相关概念和操作。 （Gitee网站） + +## Issue提交指南 + +### Issue简介 + +**名词解释**：Issue是指一项待完成的工作，这个工作可以是问题、事务、需求和建议等。每一个Issue都包含该工作的所有信息和历史，便于后来的人了解该项工作的所有方面和过程。 +**来源和作用**：Issue的概念起源于客服部门，用户打电话反馈问题，客服就创建一个工单（ticket），后继每一个处理步骤、每一次和用户的交流都要更新到工单内，记录全部的过程信息，这就是Issue的前身。随着后来的不断扩展，逐步演变成制定和实施软件开发计划的全功能项目管理工具。 +openEuler社区直接使用Gitee提供的Issue跟踪和管理系统。 + +### Issue基本功能 + +Gitee的每一个仓库内都有一个Issue面板。 + +![image](figures/contribution-guide-06.png) + +进入该面板，点击“+新建Issue”，就可以新建一个Issue，可以选择需求的类别。目前openEuler有任务、需求、缺陷、版本、翻译、CVE和安全问题等类别，每个类别对应一个提交模板，如下图所示。 + +![image](figures/contribution-guide-07.png) + +### 需求类Issue提交和处理指导 + +不同类型的Issue都有各自完整的提交和处理流程，下面以需求类Issue为例。参考以下流程图。 +![image](figures/contribution-guide-08.png) + +**步骤 1** 新建需求类Issue（Issue状态：待办） +请进入需求对应的团队或项目的repository内，选择Issue面板，点击“新建Issue”。 +如果不确定该需求对应的团队或项目，请在community-issue中创建，会有社区的开发者帮助进行归属等信息的确认。 +在标题栏的单选下拉框将Issue类型设置成“需求”，系统会自动调出需求模板。 +在标题栏**简要描述需求的要点**。 +在详细说明框内说明需求的场景和价值。 +*请注意：清晰完整的描述有助于团队成员理解，并被更快的接受和排入开发计划。* + +**步骤 2** 团队成员审核Issue（Issue状态——通过：进行中；拒绝：已拒绝 ） +**2.1** 审核后接纳 +团队成员（maintainer或者committer）审核后认为可以接纳该需求，则由审核人补充接纳需求的相关信息，并包含： +● 检查并设置该需求所属的项目。 +● 设置该需求建议合入的里程碑信息（规划版本信息）。 +● 设置该需求的优先级标签，请在标签栏选择“feature:High”、“feature:Medium”或者"feature:Low"。 +完成以上的信息以后，请将该Issue的“当前状态”调整成“进行中”（**进入步骤3**）。 +**2.2** 描述不清晰挂起 +团队成员审核后认为描述的信息不清晰，可以在该Issue的评论区留言或在邮件列表中讨论，让提交人继续补充相关信息。 +● 如果在一个月内提交人未及时补充相关信息，则系统会自动关闭该问题（**跳到步骤4**）。 +● Issue提交人补充信息后，可以通过评论让团队成员审核（**跳到步骤2**）。 +**2.3** 审核后不接纳 +团队成员审核后，由于需求价值不高等原因认为暂不接纳，可以在评论区留言或在邮件列表中讨论说明原因。确认后将Issue的“当前状态”调整成“已拒绝”（**跳到步骤4**）。 + +**步骤 3** 认领或分派Issue（Issue状态：开启） +已经进入开发阶段的需求，可以主动认领，也可以由团队成员分配。可以在评论框内输入/assign来把Issue分配给自己，或分配给其他人。 + +**步骤 4** **关闭Issue**，关闭Issue有三种情况： +需求完成后关闭，可以由认领人手工修改状态，也可以通过关联PR后，由PR审核通过后系统自动关闭。 +需求被拒接关闭，由审核人手工修改状态。 +需求超期后关闭，由系统自动根据需求停滞的时间进行超期关闭的操作。 +（openEuler Issue提交指南） + +## PR提交指南 + +Pull Request（PR）是贡献者修改源代码后，请求目标仓库采纳该修改时提交的一种请求。 + +### PR提交前验证 + +提交PR是对项目上的master主干的一次合入申请，为保证合入质量，这个动作是需要小心谨慎的。在提交PR之前，请先完成本地验证，以便在一定程度上保证在提交PR后的持续集成测试的通过。由于不同项目的本地验证方法不同，可以参考此章节内容以获取帮助。 + +### PR提交 + +**步骤 1** 提交PR请求。 +在Gitee上提交PR的具体操作，请参考下文Gitee工作流说明。为了更快得到响应，可以给PR添加标签，或提供更详细的信息，这里需要特别提示的是： +● **关联Issue**：如果提交的PR是针对某个Issue的，请在提交的描述框内添加“#”字符，此时机器人会自动关联出当前存在的Issue，你可以通过此种方式快速链接到关联的Issue。 +● **标注优先级**：可以在创建PR的时候，选择PR的优先级。或者在评论区通过/priority high给PR添加高优先级标签。 +● **标注是解决bug的合入**：可以在描述框通过输入/kind bug来标注该PR是合入解决问题的代码，以便于大家更快的回应你的PR请求。 +● **标注所属SIG**：为了方便查找，也可以在描述框通过输入sig sig-name来标识该PR所属的SIG。 + +**步骤 2** 分配评审人。 +提交PR以后，社区机器人会自动分配评审人，你也可以指定评审人。指定评审人有两种方式，可以在创建PR的时候，在右侧的下拉框中选择评审人。也可以在评论框中输入/assign @reviewer把该PR分配给对应的人。如果想把PR提交给项目的核心成员评审，以便于更快的获得批准，可以有两种方式获取到核心成员的信息： +**方式一**：该Repository的owners文件（该文件通常在该repository的根目录下）中查看，此文件保存的是所有该Repository的评审人列表。 +**方式二**：可以到该项目所属的SIG的首页内查看README.md文件，此文件会列出该SIG的负责人，所有项目以及项目的负责人。 + +**步骤 3** 自动化测试。 +如果您提交成功以后，看到PR上有openeuler-cla/no的标签，说明您还未和社区签署贡献者协议，请您先按照社区机器人的提示，完成贡献者协议的签署。具体操作详见后文。 +提交成功以后，社区机器人会启动自动化测试，为了避免浪费评审人时间，通常只有自动化测试通过的PR，评审人才会参与评审。你可以在PR的下方看到自动化测试的结果。 +如果自动化测试失败，您可以通过“Build Details”查看失败的原因。 +>![image](figures/contribution-guide-09.png) + +点击“Build Details”，可以看到具体的log信息。然后可以在里面搜索“Error”，快速的定位到错误的信息。 +修改后，你可以在评论框输入/retest命令，让社区机器人重新发起一次自动化测试。 + +**步骤 4** PR审核。 +如果审核人通过你的PR，会在评论区添加/lgtm和/approve，以表示对本次PR提交的认同。 +审核人可以在评论区发表意见，也可以在审核文件的时候，在发现问题处添加审核意见。无论哪种方式，都会在评论区显示出来。区别是，后者的评论会显示出“代码评论”，你可以通过“详情”查看评论具体指向的出处。 +为了表示对评审人意见的尊重，如果对意见有异议，请回复该意见说明原因；如果接纳评审人意见，也请做出简单的回应，便于确认后继的提交是否已按照所有接纳意见完成修改。 +**请注意，在使用/approve前至少要有一个/lgtm。** + +### 未完成PR标记 + +如果想在PR请求完成之前先征求大家的意见，有两种方法可以实现此目的： + +1. 可以在评论区添加hold或hold-cancel标签 +2. 可以在PR请求的标题中添加WIP或[WIP]前缀 + +当存在这两个标签时，将不会考虑合并你的PR请求。 + +（openEuler PR提交指南） + +## Gitee贡献工作流 + +>![image](figures/contribution-guide-10.png) + +**步骤 1** 开展工作流前的准备。 +安装Git：请先确保你的电脑上已经安装了Git软件。 +在开展Gitee的工作流之前，需要先在openEuler的代码托管平台的上找到感兴趣的Repository。如果还未找到对应的Repository，请参考此章节的内容。 + +**步骤 2** 从云上fork代码分支。 +找到并打开对应的Repository的首页。 +点击右上角的 Fork 按钮，按照指引，建立一个属于个人的云上fork分支。 +>![image](figures/contribution-guide-11.png) +>![image](figures/contribution-guide-12.png) + +**步骤 3** 把fork分支复制到本地。 +请按照以下的复制过程将Repository内的代码下载到你的在计算机上。 + +1. 创建本地工作目录：需要创建本地工作目录，以便于本地代码的查找和管理。 +```mkdir /YOUR_PATH/src/gitee.com/${your_working_dir}``` +2. 完成git上用户名和邮箱的全局配置（如果之前已经完成过此项配置，请忽略）。 +把git上的 user 设置成你gitee的个人名称： +```git config --global user.name "your Gitee Name"``` +配置你的git邮箱： +```git config --global user.mail "email@your_Gitee_email"``` +3. 完成SSH公钥注册（如果没有完成此注册，每次都要重新输入账户和密码）。 +① 生成ssh公钥。 +```ssh-keygen -t rsa -C "email@your_Gitee_email"``` +```cat ~/.ssh/id_rsa.pub``` +② 登录你个人的远程仓库网站Gitee账户并添加你的ssh公钥。 +请在Gitee网页点击右上角的“个人头像”进入个人Gitee账户，并点击个人头像下的“个人设置”，进入个人设置页面。在“个人设置->安全设置”下，点击“SSH公钥”，在“添加公钥”内把cat命令获取到的ssh公钥添加进去。 +③ 在个人电脑上完成gitee在SSH上的登记。 +```ssh -T git@gitee.com``` + +>![image](figures/contribution-guide-13.png) + +**步骤 4** 克隆远程仓库到本地。 +● 请注意openEuler有几个组织，请确认你所下载的远程仓库的组织名称 +● 可以在repository内复制远程仓库的拷贝地址，得到$remote_link： +>![image](figures/contribution-guide-14.png) + +● 在本地电脑执行拷贝命令： +把远程 fork 仓库克隆到本地 +```git clone https://gitee.com/$user_name/$repository_name``` +设置本地工作目录的 upstream 源（被 fork 的上游仓库） +```git remote add upstream https://gitee.com/openeuler/$repository_name``` +设置同步方式 +```git remote set-url --push upstream no_push``` + +**步骤 5** 拉分支（可选）。 +```git fetch upstream``` +```git checkout master``` +```git rebase upstream/master``` +从这里拉分支: +```git checkout -b work``` +然后在 work 分支上编辑和修改代码。 + +**步骤 6** 保持你的分支与master同步。 +```While on your work branch``` +```git fetch upstream``` +```git rebase upstream/master``` +执行merge的时候，请不要使用 git pull 替代上面的 fetch/rebase。因为这种方式会使提交历史变得混乱，并使代码难以理解。 +**步骤 7** 在本地工作目录提交变更。 + +提交你的变更 +```git add .``` +```git commit -m "提交原因"``` +**步骤 8** 在Gitee上创建一个 pull request。 + +1. 访问你在 的页面。 +2. 把你的分支选到提交使用的 work 分支上，点击+ Pull Request 。具体位置如下图所示： +3. 在创建新PR界面，确认源分支和目标分支，选择创建。 + +>![image](figures/contribution-guide-15.png) + +**步骤 9** 查看和回应代码审查意见。 +你提交PR申请后，PR被分配给一个或多个检视者。这些检视者将进行检视，以确保提交的正确性，不仅包括代码的正确，也包括注释和文档等。 +(Gitee工作流说明) + +## Git与 VSCode基础 + +### Git + +Git是一个免费的、开源的分布式版本控制系统，可以有效、高速地处理项目版本管理。 + +#### 基本概念 + +**工作区**：就是你在电脑里能看到的目录。 +**暂存区**：英文叫 stage 或 index。一般存放在 .git 目录下的 index 文件（.git/index）中，所以我们把暂存区有时也叫作索引（index）。 +**版本库**：工作区有一个隐藏目录 .git，这个不算工作区，而是 Git 的版本库。 +>![image](figures/contribution-guide-16.png) + +● 图中左侧为工作区，右侧为版本库。在版本库中标记为 "index" 的区域是暂存区（stage/index），标记为 "master" 的是 master 分支所代表的目录树。 +● 图中我们可以看出此时 "HEAD" 实际是指向 master 分支的一个"游标"。所以图示的命令中出现 HEAD 的地方可以用 master 来替换。 +● 当对工作区修改（或新增）的文件执行 git add 命令时，暂存区的目录树被更新，同时工作区修改（或新增）的文件内容被写入到对象库中的一个新的对象中，而该对象的ID被记录在暂存区的文件索引中。 +● 当执行提交操作（git commit）时，暂存区的目录树写到版本库（对象库）中，master 分支会做相应的更新。即 master 指向的目录树就是提交时暂存区的目录树。 +● 当执行 git reset HEAD 命令时，暂存区的目录树会被重写，被 master 分支指向的目录树所替换，但是工作区不受影响。 +● 当执行 git rm --cached \ 命令时，会直接从暂存区删除文件，工作区则不做出改变。 + +#### Git 创建仓库 + +● Git 使用 git init 命令来初始化一个 Git 仓库，Git 的很多命令都需要在 Git 的仓库中运行，所以 git init 是使用 Git 的第一个命令。在执行完成 git init 命令后，Git仓库会生成一个.git 目录，该目录包含了资源的所有元数据，其他的项目目录保持不变。 +如果当前目录下有几个文件想要纳入版本控制，需要先用 git add 命令告诉Git开始对这些文件进行跟踪，然后提交： +```$ git add *.c``` + +```$ git add README``` + +```$ git commit -m '初始化项目版本'``` + +以上命令将目录下以 .c 结尾及README文件提交到仓库中。 +>注： 在Linux系统中，commit 信息使用单引号 '，在Windows系统，commit信息使用双引号 "。 + +所以在 git bash 中 git commit -m '提交说明' 这样是可以的，在Windows命令行中就要使用双引号 git commit -m "提交说明"。 +● 我们使用 git clone 从现有 Git 仓库中拷贝项目。 +克隆仓库的命令格式为： +```git clone ``` +如果我们需要克隆到指定的目录，可以使用以下命令格式： +```git clone ``` +参数说明： +repo: Git 仓库。 +directory: 本地目录。 +比如，要克隆 Ruby 语言的 Git 代码仓库 Grit，可以用下面的命令： +```$ git clone git://github.com/schacon/grit.git``` +执行该命令后，会在当前目录下创建一个名为grit的目录，其中包含一个 .git 的目录，用于保存下载下来的所有版本记录。 +如果要自己定义要新建的项目目录名称，可以在上面的命令末尾指定新的名字： +```$ git clone git://github.com/schacon/grit.git mygrit``` + +● 我们使用如下命令设置提交代码时的用户信息。 +```$ git config --global user.name xxx``` + +```$ git config --global user.email xxx@xxx``` + +如果去掉 --global 参数只对当前仓库有效。 + +#### Git 基本操作 + +Git常用的是以下6个命令：**git clone**、**git push**、**git add** 、**git commit**、**git checkout**、**git pull** +>![image](figures/contribution-guide-17.png) + +一个简单的操作步骤： +```$ git init``` + +```$ git add .``` + +```$ git commit``` +● git init - 初始化仓库。 +● git add . - 添加文件到暂存区。 +● git commit - 将暂存区内容添加到仓库中。 +(Git菜鸟教程) + +#### Git常用命令 + +##### 创建仓库命令 + +| 命令 | 说明 | +| :-------- | :------------------------------------- | +| git init | 初始化仓库 | +| git clone | 拷贝一份远程仓库，也就是下载一个项目。 | + +##### 提交与修改命令 + +| 命令 | 说明 | +| :--------- | :--------------------------------------- | +| git add | 添加文件到暂存区。 | +| git status | 查看仓库当前的状态，显示有变更的文件。 | +| git diff | 比较文件的不同，即暂存区和工作区的差异。 | +| git commit | 提交暂存区到本地仓库。 | +| git reset | 回退版本。 | +| git rm | 将文件从暂存区和工作区中删除。 | +| git mv | 移动或重命名工作区文件。 | + +##### 提交日志 + +| 命令 | 说明 | +| :--------------- | :------------------------------------- | +| git log | 查看历史提交记录。 | +| git blame \ | 以列表形式查看指定文件的历史修改记录。 | + +##### 远程操作 + +| 命令 | 说明 | +| :--------- | :------------------- | +| git remote | 远程仓库操作。 | +| git fetch | 从远程获取代码库。 | +| git pull | 下载远程代码并合并。 | +| git push | 上传远程代码并合并。 | + +#### Git 特殊操作 + +##### 处理冲突提交 + +如果发现提交的PR带有以下的标记，说明你提交的PR和本地存在冲突，需要处理冲突。 +>![image](figures/contribution-guide-18.png) + +**步骤 1** 先将分支切换到master上，并完成master的rebase。 +```git checkout master``` +```git fetch upstream``` +```git rebase upstream/master``` + +**步骤 2** 再将分支切换到您使用的分支上，并开始rebase。 +```git checkout yourbranch``` +```git rebase master``` + +**步骤 3** 此时你可以在git上看到冲突的提示，你可以通过vi等工具查看冲突。 + +**步骤 4** 解决冲突以后，再把修改提交上去。 +```git add .``` +```git rebase --continue``` +```git push -f origin yourbranch``` + +##### 合并提交 + +如果你提交了一个PR以后，根据检视意见完成修改并再次提交了PR，不想让审阅者看到多次提交的PR，因为这不便于继续在检视中修改，那么可以合并提交的PR。合并提交的PR是通过压缩Commit来实现的。 +**步骤 1** 现在本地分支上查看日志。 +```git log``` + +**步骤 2** 然后把顶部的n个提交记录聚合到一起进入，注意n是一个数字。 +```git rebase -i HEAD~n``` +把需求压缩的日志前面的pick都改成s，s是squash的缩写。注意必须保留一个pick，如果将所有的pick都改成了s就没有合并的目标了，会发生错误。 + +**步骤 3** 修改完成以后，按ESC键，再输入:wq，会跳出一个界面，问你是否进入编辑提交备注的页面，输入e以后，进入合并提交备注的页面。请把需要合并的备注都删掉，只保留合并目标的备注，再按ESC键，输入:wq保存退出即可。 + +**步骤 4** 最后完成提交。 +```git push -f origin yourbranch``` + +**步骤 5** 回到gitee上的PR提交页面查看，您就可以看到之前的提交已经合并了。 +详细请见：。 +（Gitee工作流说明） + +### VS Code + +Visual Studio Code（简称 VS Code）是由微软开发的轻量级代码编辑器，支持包括 Markdown 在内的多种语言和格式，内置了命令行工具和 Git 版本控制系统。VSCode 中很多操作可以通过软件内命令行来使用，呼出软件内命令行的默认快捷键是 F1 或 Ctrl+Shift+P，请牢记。本文内有>前缀的命令是 VS Code 命令行的命令，否则是 Git Bash 命令。 +>![image](figures/contribution-guide-19.png) + +#### 软件与扩展安装 + +1. 安装并配置好 Git。 +2. 下载安装 VS Code。 +3. 可安装中文语言包，语言包在扩展商店中以扩展的形式提供。要打开扩展商店：点击左侧边栏的扩展图标，或快捷键 Ctrl+Shift+X，或呼出命令行，输入>extensions: install extensions 以命令打开。 +注：VSCode 软件内命令行一般不需要输入完整命令，可输入>extensions 或 >install extensions 之后用键盘上下键选择命令补全。可以输入中文命令描述。 +点击[安装]按钮即可安装，点击项目可进入商店页面查看详情。 +4. 安装 GitLens 扩展，用于 Git 相关操作。 + +>![image](figures/contribution-guide-20.png) + +#### VSCode界面和Git + +为方便解说UI内容，先将Gitee仓库用VS Code打开，这里假定你已经把 openEuler/docs仓fork到了自己的远程仓，并且 >git: clone 或用 git bash clone 到了本地计算机上： +打开本地仓：在 VS Code 中用 >git: clone 克隆完成后会提示是否打开。如果是用 Git Bash 克隆的本地仓：在Windows资源管理器中打开本地仓所在文件夹，右键菜单通过Code打开，或在VSCode中点击文件>打开文件夹，或 >File: Open Folder。打开界面如下图。 +>![image](figures/contribution-guide-21.png) + +图中已经点击预览 README\.md。单击是预览文件，文件名在打开的编辑器中显示为斜体；双击是打开文件，文件名不显示斜体。预览时做任何改动也会打开文件。 +右下角显示 Markdown 处可以点击更改语言模式，如果编辑器没有自动检测到Markdown语法可以手动选择。 +查看（预览或打开）文件时，时间线会显示当前文件的提交历史，底栏会显示光标当前所在行的作者和提交时间。点击时间线中任意提交历史可以比较查看当前文件在本次提交中的改动。 +>![image](figures/contribution-guide-22.png) + +上图在 README\.md 中做了改动但没有保存，文件名前会加上圆点图标，并且有文字提示 1 个未保存。 +如要对比本地的两个文件，在文件树（即图中 DOCS）或打开的编辑器中右键点击一个文件选择以进行比较，再右键另一个文件与已选项目进行比较，或者按住 Ctrl 选择两个文件将已选项进行比较。改动后未保存的文件也可以与已保存的版本比较。 +文件树中可以进行新建文件/文件夹、复制粘贴、重命名等常规操作。在资源管理器页，按 Ctrl+E 可以在文件树中以文件名或路径进行搜索。 +在编辑器中更改并保存文件后，有改动的文件会出现在更改中。点击这里的文件可以显示对比，即本地最新的文件与最后一次拉取的文件对比。 +在更改文件树中的文件名右侧点击 + 号将文件放入暂存区。等效于对当前文件使用 >git: stage changes 命令。 +也可以 Ctrl+左键多选文件后点击 + 批量放入暂存区。命令 >git:stage all changes 可以把所有更改的文件放入暂存区。 +点击暂存区中文件名右侧的 - 可以移出暂存区。 +要提交暂存区中的文件，按源代码管理项下输入框中的提示，输入提交信息按 Ctrl+Enter 提交。等效于 >git: commit staged。 +未暂存的文件可以使用 >git: commit 或 >git: commit all 提交，确认后文件可跳过暂存直接提交。 +提交的文件存放于本地库中，还未发布到远端库。可以使用 >git: undo last commit 撤消最后一次提交。 +提交后，窗口左下角会显示提交的数量，可以点击此处发布到远端库（同时会拉取远端库的新提交）。如果要只发布而不拉取，可以使用 >git: push。如果显示远端库有新提交，先拉取至本地，以免提交后产生冲突。 +>![image](figures/contribution-guide-23.png) + +**COMMITS** 项显示当前分支中的所有提交历史。点击提交项可以展开显示更改的文件，点击文件可以显示与上个版本比较的改动。 +>![image](figures/contribution-guide-24.png) + +FILE HISTORY 即编辑器中当前打开文件的提交历史，类似于资源管理器页中的时间线。 +BRANCHES 显示本地分支中的提交。参见下文 REMOTES。 +REMOTES 显示远端库中所有分支的提交。右键选择 Switch to Branch... 切换到另一分支，并将这个分支保存到本地，显示在 BRANCHES 中。点击左下此处也可以切换分支。 +>![image](figures/contribution-guide-25.png) +>STASHES 储藏区。修改后的文件如果不满意，不想放在本次提交里，或者有未提交的更改但想要切换到其他分支进行操作，可以 >git: stash 先放入储藏区。 +>TAGS 列出每个标签对应的提交。 +>SEARCH & COMPARE 提供搜索提交和比较分支的功能。Search Commits... 可以选择按消息内容、作者、文件等搜索。Compare References... 可以选中两个分支进行比较，提交比较和文件树比较。文件树比较会显示文件路径变化，以及内容有差异的同名文件。 +>![image](figures/contribution-guide-26.png) + +创建图中的比较时，先选择了 master 分支（显示在右侧），后选择了 stable2-21.09 分支（显示在左侧）。 +文件树中 - 号表示在右侧分支中缺少的文件，+ 号表示右侧分支中多出的文件，± 表示同名文件内容有差异，点击打开对比视图。 + +#### 保持本地提交记录和远端上游仓同步 + +为防止创建的Pull Request与上游仓内容冲突，强烈建议每次提交前将上游仓的 commit 拉取到当前分支。 + +**步骤 1** 在VS Code中添加上游仓。以主仓openEuler/docs为例，在网页端克隆/下载按钮复制SSH地址 git\@gitee.com:xxxx.git。运行以下命令添加主仓，显示在源代码管理页的REMOTE下: +```git remote add upstream git@gitee.com:xxxx.git``` +upstream 为自定义名称 + +**步骤 2** 抓取主仓的commits。 +```git fetch upstream``` +```git fetch upstream``` + +**步骤 3** 将主仓的commits合并到本地的分支。以 master 分支为例： +```git checkout master``` +↑切换到 master 分支，如已在 VS Code 中切换则省略 +```git merge upstream/master``` + +**步骤 4** 解决源代码管理中提示的冲突（如有），然后提交自己的改动。 + +#### 合并commits + +为保持提交记录简洁（以及满足部分仓库的要求），一个 PR 应当只包含一个 commit。如果多个 commits已经提交到远端库，靠回退版本 (git reset)来合并 commits。 +假设**源代码管理 > COMMITS** 当前的 commit 记录如下： + +```text + YOUR_COMMIT_3 + YOUR_COMMIT_2 + YOUR_COMMIT_1 + OTHERS_COMMIT_2 + OTHERS_COMMIT_1 +``` + +要合并 YOUR_COMMIT_，（记录下 commit message）右键点击 OTHERS_COMMIT_2 选择 Reset Current Branch to Commit...，然后选择 Soft Reset，即可回退到 OTHERS_COMMIT_2 的版本，三个 YOUR_COMMIT_ 的改动会回到上方更改区域，重新填写commit message 强制提交即可。 +版本回退后，因为本地的版本早于远端库的版本，必须**使用 force push 覆盖远端库**：打开 VS Code 选项，搜索 Allow Force Push 项并勾选，然后按 F1 呼出命令行，输入 push force 等类似关键字，选择相关选项。 + +#### 推荐扩展 + +● Markdown Editor (zaaack.markdown-editor)，支持所见即所得模式和分屏预览模式的 Markdown 编辑器。 +● Markdown Preview Enhanced (shd101wyy.markdown-preview-enhanced)，增强 Markdown 预览功能，包含 TOC 自动生成功能。快捷方式同样为 Ctrl+Shift+V，覆盖 VSCode 自带的预览查看器。安装后如果需要使用自带的预览查看器，在编辑器窗口顶端的文件标签上右键 -> 打开预览。自带的查看器中，双击句段可以跳转到原文相应句子。 +自动生成 TOC：>markdown preview enhanced: create toc （需要保持预览窗口打开）。保存时自动更新 TOC。 +● GitHub Markdown Preview (bierner.github-markdown-preview)，或仅安装其中的核心扩展 Markdown Preview Github Styling (bierner.markdown-preview-github-styles)，以 GitHub 格式显示 Markdown 预览，效果接近Gitee网页。 +● Code Spell Checker (streetsidesoftware.code-spell-checker)，自然语言拼写检查扩展，除英语外还有多种语言可选。 +● CJK Word Handler (sharzyl.cjk-word-handler)。VSCode 默认以空格、","、"." 等英文符号作为分隔符，导致整句中文被识别为一个整词，使用 Ctrl+←/→ 相关操作时非常不便。这个扩展可以让 VSCode 支持中文分词逻辑。 +● Bookmarks (alefragnani.bookmarks)，以行为坐标添加书签。 +（VSCode for openEuler Docs Globalization）。 + +## 参考链接 + +[https://kaiyuanshe.cn/article/github/how-to-participate-in-open-source/](https://kaiyuanshe.cn/article/github/how-to-participate-in-open-source/) +[https://docs.qq.com/doc/DSnJVSmhDcHhrV25L](https://docs.qq.com/doc/DSnJVSmhDcHhrV25L) +[https://www.openeuler.org/zh/](https://www.openeuler.org/zh/) +[https://gitee.com/openeuler/community/blob/master/zh/contributors/issue-submit.md](https://gitee.com/openeuler/community/blob/master/zh/contributors/issue-submit.md) +[https://gitee.com/openeuler/community/blob/master/zh/contributors/pull-request.md](https://gitee.com/openeuler/community/blob/master/zh/contributors/pull-request.md) +[https://gitee.com/openeuler/community/blob/master/zh/contributors/Gitee-workflow.md](https://gitee.com/openeuler/community/blob/master/zh/contributors/Gitee-workflow.md) +[https://www.runoob.com/git/git-tutorial.html](https://www.runoob.com/git/git-tutorial.html) +[https://gitee.com/openeuler/G11N/blob/master/learning-materials/open-source-basics/vscode-for-g11n.md](https://gitee.com/openeuler/G11N/blob/master/learning-materials/open-source-basics/vscode-for-g11n.md) +[https://gitee.com/openeuler/globalization/blob/master/openeuler-g11n-contribution-guide.md](https://gitee.com/openeuler/globalization/blob/master/openeuler-g11n-contribution-guide.md) +[https://gitee.com/openeuler/G11N/blob/master/learning-materials/open-source-basics/markdown-basics.md](https://gitee.com/openeuler/G11N/blob/master/learning-materials/open-source-basics/markdown-basics.md) diff --git a/docs/zh/contribute/public_sys-resources/icon-caution.gif b/docs/zh/contribute/public_sys-resources/icon-caution.gif new file mode 100644 index 0000000000000000000000000000000000000000..6e90d7cfc2193e39e10bb58c38d01a23f045d571 Binary files /dev/null and b/docs/zh/contribute/public_sys-resources/icon-caution.gif differ diff --git a/docs/zh/contribute/public_sys-resources/icon-danger.gif b/docs/zh/contribute/public_sys-resources/icon-danger.gif new file mode 100644 index 0000000000000000000000000000000000000000..6e90d7cfc2193e39e10bb58c38d01a23f045d571 Binary files /dev/null and b/docs/zh/contribute/public_sys-resources/icon-danger.gif differ diff --git a/docs/zh/contribute/public_sys-resources/icon-note.gif b/docs/zh/contribute/public_sys-resources/icon-note.gif new file mode 100644 index 0000000000000000000000000000000000000000..6314297e45c1de184204098efd4814d6dc8b1cda Binary files /dev/null and b/docs/zh/contribute/public_sys-resources/icon-note.gif differ diff --git a/docs/zh/contribute/public_sys-resources/icon-notice.gif b/docs/zh/contribute/public_sys-resources/icon-notice.gif new file mode 100644 index 0000000000000000000000000000000000000000..86024f61b691400bea99e5b1f506d9d9aef36e27 Binary files /dev/null and b/docs/zh/contribute/public_sys-resources/icon-notice.gif differ diff --git a/docs/zh/contribute/public_sys-resources/icon-tip.gif b/docs/zh/contribute/public_sys-resources/icon-tip.gif new file mode 100644 index 0000000000000000000000000000000000000000..93aa72053b510e456b149f36a0972703ea9999b7 Binary files /dev/null and b/docs/zh/contribute/public_sys-resources/icon-tip.gif differ diff --git a/docs/zh/contribute/public_sys-resources/icon-warning.gif b/docs/zh/contribute/public_sys-resources/icon-warning.gif new file mode 100644 index 0000000000000000000000000000000000000000..6e90d7cfc2193e39e10bb58c38d01a23f045d571 Binary files /dev/null and b/docs/zh/contribute/public_sys-resources/icon-warning.gif differ diff --git "a/docs/zh/contribute/\346\226\207\346\241\243\344\270\255\345\277\203\346\224\271\347\211\210\345\215\207\347\272\247.md" "b/docs/zh/contribute/\346\226\207\346\241\243\344\270\255\345\277\203\346\224\271\347\211\210\345\215\207\347\272\247.md" new file mode 100644 index 0000000000000000000000000000000000000000..f9f0cfe8aa94fd174ddbc5a6e8c61f8bb87ffc7d --- /dev/null +++ "b/docs/zh/contribute/\346\226\207\346\241\243\344\270\255\345\277\203\346\224\271\347\211\210\345\215\207\347\272\247.md" @@ -0,0 +1,26 @@ +# 文档中心升级指南 + +## 资料发布流程整改 + +![image](figures/contribution-guide-27.png) + +特性文档生产下沉到各SIG组，通过文档模版和写作规范，保障文档质量。 + +## 各SIG组创建自己的docs仓 + +![image](figures/contribution-guide-28.png) + +以CloudNative SIG组为例，新建openeuler/CloudNative-docs仓库来维护云原生的相关文档。仓库命名规范：openeuler/SIG组名-docs + +## 在docs仓中维护文档 + +### 原本存放在docs仓的文档，直接移动到SIG组的docs仓下 + +![image](figures/contribution-guide-29.png) + +[docs仓](https://gitee.com/openeuler/docs/tree/test/docs/zh/docs/1newStruct)的存量文档已按照最新的目录设计整理划分，各SIG组只需将整理好的文件夹移到新建的SIG组doc仓。 + +### 游离在docs仓外的文档，新增到SIG组的docs仓下 + +1. 文档转成md格式，进行[markdownlint检查](./markdownlint检查规则.md)，自动化问题修复可参考[markdownlint 错误修复工具](./markdownlint错误修复工具.md)。 +2. 添加index文件，指明文档目录结构。