文档¶

本入门指南将帮助您获取贡献文档所需的工具和知识。

如果你不熟悉 reStructuredText 语言，请阅读 reStructuredText 语言介绍。然后，有两种方式可以开始为文档做出贡献：

对于较小的更改，例如添加段落或修复拼写错误，我们推荐 使用 GitHub 界面。这是提交更改最简单快捷的方式，适合非技术人员。直接跳转到贡献文档部分开始操作。
对于更复杂的更改，例如添加新页面，有必要 使用 Git 并从文档的本地副本中工作。首先按照环境设置部分中的说明准备您的环境。

另请参阅

Discover other ways to contribute to Odoo

重构文本 (RST)¶

文档采用 reStructuredText (RST) 编写，这是一种轻量级标记语言，由常规文本增强标记组成，允许包含标题、图像、注释等。 RST 易于使用，即使您不熟悉它。

重要

在编写文档时，请注意我们的内容和 RST 指南。这确保了文档的一致性，并有助于 Odoo 团队批准更改。

环境设置¶

下面的说明帮助您准备环境以便在本地对文档进行修改，然后将其推送到 GitHub。如果您已经完成了这一步骤或者想要从 GitHub 界面进行修改，请跳过本节并转到贡献文档。

首先，创建一个 GitHub 账户。Odoo 使用 GitHub 来管理其产品的源代码，这也是你提交更改的地方。
Generate a new SSH key and register it on your GitHub account.
前往 github.com/odoo/documentation 并点击右上角的 Fork 按钮来创建一个分支 (你自己的副本) 到你的账户。这将创建一个代码库的副本，你可以在其中进行更改而不影响主要代码库。如果你在 Odoo 工作，则跳过此步骤。
Install Git. It is a command-line (a text interface) tool that allows tracking the history of changes made to a file and, more importantly, working on different versions of that file simultaneously. It means you do not need to worry about overwriting someone else’s pending work when making changes.

请确认 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 将更改推送到您的 fork 而不是主代码库。在下面的命令中，将 <your_github_account> 替换为您创建 fork 的 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
```
验证 Python 依赖项的安装目录是否包含在系统的 PATH 变量中。

按照在Linux和macOS上更新PATH变量的指南，使用Python依赖项的安装路径（默认为 ~/.local/bin）进行操作。
安装 Make。
$ sudo apt install make -y
请按照在Windows上安装Make的指南进行操作。
Install pngquant.
你现在已经准备好使用 Git 进行首次贡献了。

贡献文档¶

首先，创建一个 GitHub 账户。Odoo 使用 GitHub 来管理其产品的源代码，这也是你提交更改的地方。
请确认您正在浏览您想要更改的文档版本。您可以从顶部菜单中的下拉菜单中选择版本。
前往您想要更改的页面，然后点击页面右上角的在 GitHub 上编辑按钮。
点击 Fork this repository 按钮创建一个分支 (你自己的副本) 到你的账户上。这将创建一个代码库的副本，你可以在其中进行更改而不影响主要的代码库。如果你在 Odoo 工作，则跳过此步骤。
在进行所需更改时，请注意遵循 content 和 RST 指南。

小技巧
点击预览更改按钮以以更易读的格式查看您的贡献。请注意，预览无法正确处理所有标记。例如，注释和提示将显示为纯文本。
滚动到页面底部并填写小表单以提出您的更改。在第一个文本框中，写下您更改的非常简短的摘要。例如，”修复一个拼写错误”或”添加销售订单发票的文档”。在第二个文本框中，解释 为什么 您提出这些更改。然后，点击提出更改按钮。
审核您的更改并单击创建拉取请求按钮。
勾选 Allow edits from maintainer 复选框。如果你在 Odoo 工作，则跳过此步骤。
查看您撰写的关于更改的摘要，然后再次点击创建拉取请求按钮。
在页面底部，检查合并状态并解决任何问题。
一旦你的 PR 准备好合并，Odoo 团队的一名成员将自动被分配进行审查。如果审查者有问题或意见，他们会将其作为评论发布，你将通过电子邮件收到通知。这些评论必须得到解决，贡献才能继续推进。
一旦您的更改获得批准，审阅者会将其合并，它们将在第二天上线。

重要

一些步骤需要熟悉 Git。如果你在某个地方卡住了，这里有一些教程和一个交互式训练。

现在您的环境已经设置好，您可以开始为文档做出贡献。在终端中，导航到您克隆源代码的目录，并按照下面的指南操作。

选择您想要进行更改的文档版本。请记住，针对不受支持的 Odoo 版本的贡献不会被接受。本指南假设更改针对的是 Odoo 18 的文档，该版本对应于分支 18.0。
从分支 18.0 创建一个新分支。分支名称的前缀应为基分支：18.0-...。如果你在 Odoo 工作，请在分支名称后缀上你的 Odoo 句柄：18.0-...-xyz。
Example
```
$ git switch -c 18.0-explain-pricelists
```
```
$ git switch -c 18.0-explain-pricelists-xyz
```
在进行所需更改时，请注意遵循 content 和 RST 指南。

压缩所有已添加或修改的 PNG 图像。

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

为每个重命名的 RST 文件编写一条 redirect rule 。
使用 make 构建文档。然后，在网页浏览器中打开 _build/index.html 以浏览包含您更改的文档。

小技巧
使用 make help 命令来了解其他有用的命令。
提交您的更改。按照 Git指南中的说明编写清晰的提交消息。
```
$ git add .
$ git commit
```
将您的更改推送到您的分支，我们为其添加了远程别名 dev。
Example
```
$ git push -u dev 18.0-explain-pricelists
```
如果你在Odoo工作，请直接将你的更改推送到主代码库，其远程别名为 origin。
Example
```
$ git push -u origin 18.0-explain-pricelists-xyz
```
在 GitHub 上打开一个 PR 来提交你的更改以供审查。
1. 前往 odoo/documentation 代码库的比较页面.
2. 选择 18.0 作为基础。
3. 点击 compare across forks.
4. 选择 <your_github_account>/odoo 作为主仓库。将 <your_github_account> 替换为您在 GitHub 上创建分支的账户名。如果您在 Odoo 工作，则跳过此步骤。
5. 审核您的更改并单击创建拉取请求按钮。
6. 勾选 Allow edits from maintainer 复选框。如果你在 Odoo 工作，则跳过此步骤。
7. 完成描述并再次点击创建拉取请求按钮。
在页面底部，检查合并状态并解决任何问题。
一旦你的 PR 准备好合并，Odoo 团队的一名成员将自动被分配进行审查。如果审查者有问题或意见，他们会将其作为评论发布，你将通过电子邮件收到通知。这些评论必须得到解决，贡献才能继续推进。
一旦您的更改获得批准，审阅者会将其合并，它们将在第二天上线。

Edit on GitHub