手册文档¶

本入门指南将帮助你掌握为文档做贡献所需的工具与知识。

如果你不熟悉 reStructuredText 语言简介，请先阅读它。之后，可以通过以下两种方式开始为文档做贡献：

对于较小的改动，例如添加一个段落或修正拼写错误，我们建议 使用 GitHub 界面。这是提交改动最简单、最快的方式，也适合非技术人员。请直接跳到为文档做贡献章节开始。
对于更复杂的改动，例如添加新页面，则必须 使用 Git，并基于文档的本地副本工作。请先按照环境设置章节中的说明准备好你的环境。

reStructuredText (.rst)文件格式¶

文档使用 reStructuredText （RST）编写，这是一种轻量级标记语言，由普通文本加上标记构成，可以包含标题、图片、注释等。对于 RST 而言，即使你不熟悉它，使用起来也不困难。

重要

编写文档时，请注意我们的内容和 RST 规范。这样可以确保文档保持一致，也便于 Odoo 团队批准你的改动。

环境设置¶

以下说明帮助您准备好环境，以便在本地修改文档并将其推送到 GitHub。如果您已完成此步骤，或希望从 GitHub 界面进行更改，请跳过本节并前往为文档做贡献。

首先，创建一个 GitHub 账号。Odoo 使用 GitHub 管理其产品的源代码，你将在那里提交你的改动。
生成一个新的 SSH 密钥并注册到你的 GitHub 账户
访问 github.com/odoo/documentation，点击右上角的 Fork 按钮，在您的账户中创建该仓库的分支（您自己的副本）。这样会创建一个代码库副本，您可以在其中进行更改而不影响主代码库。如果您在 Odoo 工作，请跳过此步骤。
安装 Git。它是一款命令行（文本界面）工具，可以跟踪对文件所做更改的历史记录，更重要的是，可以同时处理该文件的不同版本。这意味着您在进行更改时，不必担心覆盖其他人尚未完成的工作。

验证 Git 的安装目录是否已包含在系统的 PATH 变量中。

参照在 Linux 和 macOS 上更新 PATH 变量的指南，使用 Git 的安装路径（默认为 /usr/bin/git）。
配置 Git 以识别你未来贡献的作者身份。输入你注册时用来在GitHub上的同一个邮箱地址。
```
$ git config --global user.name "Your Name"
$ git config --global user.email "youremail@example.com"
```

使用 Git 克隆源代码，并进入本地仓库目录。

$ git clone git@github.com:odoo/documentation.git
$ cd documentation

配置 Git，将更改推送到您的分支而不是主代码库。在下面的命令中，请将 <your_github_account> 替换为您创建分支所用的 GitHub 账户名。如果您在 Odoo 工作，请跳过此步骤。
```
$ git remote add dev git@github.com:<your_github_account>/documentation.git
```

配置 Git，以便来自不同系统的撰写者之间更轻松地协作。

$ git config --global core.autocrlf input
$ git config commit.template `pwd`/commit_template.txt

$ git config --global core.autocrlf true
$ git config commit.template %CD%\commit_template.txt

安装最新版本的 Python 和 pip。
使用 pip 安装文档所需的 Python 依赖项。
```
$ pip install -r requirements.txt
```
请确认系统的 PATH 环境变量中已包含 Python 依赖项的安装目录。

按照在 Linux 和 macOS 上更新 PATH 变量的指南操作，使用 Python 依赖项的安装路径（默认为 ~/.local/bin）。
安装 Make。
$ sudo apt install make -y
按照在 macOS 上安装 Make 的指南操作

按照在 Windows 上安装 Make 的指南操作。
安装 pngquant。
现在，你已准备好使用 Git 完成你的第一次贡献。

为文档做贡献¶

首先，创建一个 GitHub 账号。Odoo 使用 GitHub 管理其产品的源代码，你将在那里提交你的改动。
请确认您正在浏览的文档版本是您想要更改的版本。可在顶部菜单的下拉列表中选择版本。
前往您想要更改的页面，点击页面右上角的在 GitHub 上编辑按钮。
点击 Fork this repository 按钮，在您的账户中创建该仓库的派生副本（您自己的副本）。这样会创建代码库的一个副本，您可以在其中进行更改，而不会影响主代码库。如果您就职于 Odoo，请跳过此步骤。
进行所需的更改，同时注意遵循内容和 RST 准则。

小技巧
点击 Preview changes 按钮，以更易读的格式查看您的贡献内容。请注意，预览无法正确处理所有标记。例如，注释和提示会显示为纯文本。
滚动到页面底部，填写小型表单以提交您的更改建议。在第一个文本框中，简要概括您的更改内容。例如，“修正拼写错误”或“添加销售订单开票的文档”。在第二个文本框中，说明您 为什么 提出这些更改。然后，点击 Propose changes 按钮。
检查您的更改，然后点击 Create pull request 按钮。
勾选 Allow edits from maintainer 复选框。如果您在 Odoo 工作，请跳过此步骤。
检查您撰写的更改摘要，然后再次点击 Create pull request 按钮。
页面底部，检查合并状态并解决任何问题。
一旦你的 PR（拉取请求）可以合并，Odoo 团队的成员就会被自动指派进行审查。如果审查者有疑问或意见，会以评论的形式提出，你会收到邮件通知。必须解决这些评论，贡献才能继续推进。
改动获得批准后，审查者会将其合并，改动会在第二天上线。

重要

本指南的某些步骤需要您熟悉 Git。如果您在某些环节遇到困难，可以参考这些教程和这个互动式培训。

环境设置完成后，您就可以开始为文档做贡献了。在终端中，进入您克隆源代码所在的目录，并按照以下指南操作。

选择你想要修改的文档版本。请记住，针对不受支持的 Odoo 版本的贡献不会被接受。本指南假设修改针对的是 Odoo 20 的文档，对应分支 20.0。
从 20.0 分支创建一个新分支。在分支名前加上基础分支前缀：20.0-...。如果你在 Odoo 工作，请在分支名后加上你的 Odoo 用户名后缀：20.0-...-xyz。
示例
```
$ git switch -c 20.0-explain-pricelists
```
```
$ git switch -c 20.0-explain-pricelists-xyz
```
进行所需的更改，同时注意遵循内容和 RST 准则。

压缩所有新增或修改过的 PNG 图片。

$ pngquant path/to/image.png
$ mv path/to/image-fs8.png path/to/image.png

为每个被重命名的 RST 文件编写一条重定向规则。
使用 make 构建文档。然后，在 Web 浏览器中打开 _build/index.html，浏览包含你改动的文档效果。

小技巧
使用 make help 了解其他有用的命令。
提交您的更改。按照 Git 规范中的说明编写清晰的提交信息。
```
$ git add .
$ git commit
```
将你的改动推送到你的 fork，我们已为其添加了远程别名 dev。
示例
```
$ git push -u dev 20.0-explain-pricelists
```
如果您就职于 Odoo，请将更改直接推送到主代码库，其远程别名为 origin。
示例
```
$ git push -u origin 20.0-explain-pricelists-xyz
```
在 GitHub 上发起 PR（拉取请求），提交您的更改以供审核。
1. 转到 odoo/documentation 代码库的比较页面。
2. 为基础分支选择 20.0。
3. 点击 compare across forks。
4. 选择 <your_github_account>/odoo 作为源仓库（head repository）。将 <your_github_account> 替换为您创建派生副本时使用的 GitHub 账户名称。如果您就职于 Odoo，请跳过此步骤。
5. 检查您的更改，然后点击 Create pull request 按钮。
6. 勾选 Allow edits from maintainer 复选框。如果您在 Odoo 工作，请跳过此步骤。
7. 填写描述，然后再次点击 Create pull request 按钮。
页面底部，检查合并状态并解决任何问题。
一旦你的 PR（拉取请求）可以合并，Odoo 团队的成员就会被自动指派进行审查。如果审查者有疑问或意见，会以评论的形式提出，你会收到邮件通知。必须解决这些评论，贡献才能继续推进。
改动获得批准后，审查者会将其合并，改动会在第二天上线。