文档¶

本介绍性指南将帮助您获得编写文档所需的工具和知识。

如果您不熟悉，请阅读 introduction to the reStructuredText language。然后，有两个行动方案可以开始为文档做出贡献：

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

其他资料

Discover other ways to contribute to Odoo

重构文本 (RST)¶

该文档以 reStructuredText (RST) 编写，这是一种 lightweight markup language，由带有标记的常规文本组成，允许包含标题、图像、注释等。 RST 很容易使用，即使您不熟悉它。

重要

编写文档时请注意我们的 content 和 RST 准则。这可确保文档保持一致并促进 Odoo 团队批准变更。

环境设置¶

以下说明可帮助您准备环境以对文档进行本地更改，然后将其推送到 GitHub。如果您已完成此步骤或想要从 GitHub 界面进行更改，请跳过此部分并转到为文档做出贡献。

首先，create a GitHub account。 Odoo 使用 GitHub 来管理其产品的源代码，您可以在此处提交更改。
Generate a new SSH key and register it on your GitHub account。
转到 github.com/odoo/documentation 并单击右上角的 Fork 按钮，在您的帐户上创建存储库的分叉 (your own copy)。这将创建代码库的副本，您可以对其进行更改，而不会影响主代码库。如果您在 Odoo 工作，请跳过此步骤。
Install Git。它是一个命令行 (a text interface) 工具，允许跟踪文件更改的历史记录，更重要的是，可以同时处理该文件的不同版本。这意味着您在进行更改时无需担心覆盖其他人的待处理工作。

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

guide to update the PATH variable on Linux and macOS 后面是 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
```
验证 Python 依赖项的安装目录是否包含在系统的 PATH 变量中。

guide to update the PATH variable on Linux and macOS 后面是 Python 依赖项的安装路径（默认为 ~/.local/bin）。
安装制作。
$ sudo apt install make -y
遵循 guide to install Make on macOS

遵循 guide to install Make on Windows。
Install pngquant。
您现在已准备好使用 Git make your first contribution。

为文档做出贡献¶

首先，create a GitHub account。 Odoo 使用 GitHub 来管理其产品的源代码，您可以在此处提交更改。
确认您正在浏览要更改的版本中的文档。可以从顶部菜单的下拉列表中选择版本。
前往您要更改的页面，然后单击页面右上角的 Edit on GitHub 按钮。
单击 Fork this repository 按钮在您的帐户上创建存储库的分叉 (your own copy)。这将创建代码库的副本，您可以对其进行更改，而不会影响主代码库。如果您在 Odoo 工作，请跳过此步骤。
进行所需的更改，同时遵循 content 和 RST 准则。

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

重要

本指南的某些步骤需要熟悉 Git。如果您在某个时刻遇到困难，这里有一些 tutorials 和 interactive training。

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

选择您要更改的文档版本。请记住，不接受针对 unsupported version of Odoo 的贡献。本指南假设更改针对 Odoo 19 的文档，该文档对应于分支 19.0。
从分支 19.0 开始创建一个新分支。在分支名称前加上基本分支的前缀：19.0-...。如果您在 Odoo 工作，请在分支名称后加上您的 Odoo 句柄：19.0-...-xyz。
Example
```
$ git switch -c 19.0-explain-pricelists
```
```
$ git switch -c 19.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 构建文档。然后，在 Web 浏览器中打开 _build/index.html 以浏览包含更改的文档。

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