首次贡献者¶

开始为 OpenStack 文档做出贡献的最佳方式之一是手动完成安装指南。在操作过程中做笔记，并通过在 Launchpad 上提交文档错误来提出改进建议。

准备贡献¶

首先设置您的 OpenStack 帐户，然后设置 Gerrit。

要设置您的贡献环境，请继续执行以下子部分。

设置文本编辑器¶

使用您选择的任何文本编辑器来处理文档。选择支持拼写检查和 RST 语法高亮显示的编辑器是一个好主意。例如

为了保持文档的整洁和易于比较，所有 OpenStack 项目都要求文本换行在 79 个字符以内，并且行尾没有空格。

您可以配置文本编辑器自动执行此操作。

例如，在 .vimrc 中

set list
set listchars=tab:>-,trail:-,extends:#,nbsp:-
set modeline
set tw=78
set tabstop=8 expandtab shiftwidth=4 softtabstop=4

设置 git 和 git-review¶

安装 git。有关详细信息，请参阅 GitHub 帮助。

如果您使用 Windows 为 OpenStack 贡献代码，请安装 Git for Windows。在后续过程中，请从 Git Bash 控制台运行命令。
安装 git-review，以便您可以提交补丁。有关详细信息，请参阅安装 git-review。

注意

如果您使用 Windows 为 OpenStack 贡献代码，请安装 Python 作为先决条件。在 Python 安装过程中，请务必按照说明安装 setuptools 和 pip。

设置 SSH¶

在您提交的计算机上，生成一个 SSH 密钥
```
$ ssh-keygen –t rsa
```
可选地，输入密码。如果您输入密码，请记住它，因为您每次提交时都必须输入它。

查看并复制您的 SSH 密钥

Linux/Mac

$ less ~/.ssh/id_rsa.pub

Windows

$ notepad ~/.ssh/id_rsa.pub

登录到 gerrit https://review.opendev.org/。
在右上角，单击您的用户名。单击设置 > SSH 公钥页面。单击 添加密钥。将密钥粘贴到 添加 SSH 公钥 Web 表单中，然后单击 添加。

设置仓库¶

有关如何设置仓库以便您可以在本地对其进行操作的说明，请参阅 Infrastructure 手册的开始一个新项目的工作。

如果您在仓库设置方面遇到困难，请参阅故障排除设置。

查找错误¶

在设置好贡献环境后，是时候找到一些可以处理的事情了

转到 Bugs:openstack-manuals 上的错误列表，以获取与 openstack-manuals 仓库相关的文档错误。

对于特定项目的文档错误，请转到 https://bugs.launchpad.net/<projectname>。
找到已被其他贡献者确认并分配给您的错误。

有关文档错误的更多信息，请参阅文档错误。

提交更改¶

按照 Infrastructure 手册的开始更改部分所述，更新仓库并创建一个新的主题分支。
修复文档中的错误。

阅读写作风格，并注意 RST 约定。
创建您的提交消息。有关详细信息，请参阅提交更改。
按照提交更改以供审核说明，为 review.opendev.org 创建一个补丁。
按照 git-review 返回的 URL 检查您的提交
```
https://review.opendev.org/<COMMIT-NUMBER>
```
在 Gerrit 中，等待自动 Zuul 检查成功。

庆祝并等待审核！

参见

故障排除设置
构建文档

响应请求¶

提交补丁后，审核人员可能会要求您在他们批准补丁之前进行更改。

要提交对补丁的更改，请执行以下步骤

从 review.opendev.org URL 中复制提交编号。
在命令行中，更改到您仓库的本地副本。
签出补丁
```
$ git review -d <COMMIT-NUMBER>
```
进行您的编辑。
使用 amend 标志提交更改
```
$ git commit -a --amend
```
确保 Change-ID 行保留在您的提交消息中。这可以防止 Gerrit 创建新的补丁。
按照 Infrastructure 手册的更新更改部分所述，将更改推送到 review。

等待更多审核。

故障排除设置¶

git 和 git review¶

真实性错误

第一次运行 git review 时，您可能会看到此错误
```
The authenticity of host '[review.opendev.org]:29418 ([104.130.246.32]:29418) can't be established.
```
在提示符处键入 yes（所有三个字母）。
Gerrit 连接错误

首次连接到 gerrit 时，您可能会看到此错误
```
Could not connect to gerrit.
Enter your gerrit username:
```
输入与 review.opendev.org 上设置页面中的用户名匹配的用户名。

不是 git 仓库错误

如果您看到此错误

fatal: Not a git repository (or any of the parent directories): .git
You are not in a directory that is a git repository: A .git file was not found.

更改到您仓库的本地副本并重新运行该命令。

Gerrit 位置未知错误

如果您看到此错误
```
We don't know where your gerrit is. Please manually create a remote named "gerrit" and try again.
```
您需要创建一个 git remote，该 remote 映射到您的仓库的 review.opendev.org SSH 端口。例如，对于具有 username_example 用户名的用户和 openstack-manuals 仓库，您应该运行此命令
```
git remote add gerrit ssh://username_example@review.opendev.org:29418/openstack/openstack-manuals.git
```
远程拒绝错误

如果您看到此错误
```
! [remote rejected] HEAD -> refs/publish/2025.2/addopenstackdocstheme (missing Change-Id in commit message footer)
```
首次设置 gerrit remote 并尝试为 review.opendev.org 创建补丁时，您可能会看到此消息，因为该工具需要对您的提交消息进行一次编辑，以便自动插入 Change-Id。如果发生这种情况，请运行 git commit -a --amend，保存提交消息，然后再次运行 git review -v。
权限被拒绝错误

如果您看到此错误
```
Permission denied (publickey).
```
双重检查 https://review.opendev.org/ 上的设置页面，以确保计算机或虚拟服务器上的公共密钥已复制到 SSH 公钥。如果您尚未调整 .ssh 配置，您的系统可能没有使用正确的密钥连接到 gerrit。

在 Mac 或 Linux 上使用以下命令列出您的本地公共密钥：
```
less ~/.ssh/id_rsa.pub
```
在 Windows 上，在相同的位置查找它。

如果您仍然收到 Permission denied (publickey) 消息，您可能需要检查您是否遇到了 no mutual signature algorithm。任何运行 OpenSSH 8.8 或更高版本的系统都会禁用默认情况下使用 SHA-1 散列算法的 RSA 签名。尝试运行以下命令：
```
ssh -vv -p 29418 {username}@review.opendev.org
```
如果您看到 no mutual signature algorithm，您需要考虑使用另一种算法代替 RSA。例如，使用 ed25519 生成您的密钥并上传 id_ed25519.pub。
```
ssh-keygen -t ed25519 -C "your_email@example.com"
```
合并冲突，需要 rebase

有时您的更改会与另一个补丁产生合并冲突。在这种情况下，您需要在仓库的当前状态上重新 rebase 您的提交。在许多情况下，可以通过在 gerrit 界面中按 Rebase 按钮来实现。如果这失败了，您必须手动 rebase。

有关解决合并冲突的基本介绍，请参阅 GitHub 文章在 git rebase 之后解决合并冲突。
在 Gerrit 中您的提交的 Zuul 检查 部分中出现 FAILURE
1. 单击 FAILURE 测试旁边的链接。
2. 验证 console.html 的输出
  - 如果它包含与您的提交相关联的问题文件名和行号的错误或警告，请修复问题并将新的更改推送到 review。
  - 如果问题与您的提交无关，请通过在 Gerrit 审核的评论部分留下“recheck”一词来重新运行 gate 作业。
参见
- 自动化测试
- 构建任务

网络¶

如果您的网络连接不稳定，您可能会看到此错误

Read from socket failed: Connection reset by peer

当您的网络连接改善时，请重试。

通过 HTTP/HTTPS 访问 gerrit

如果您怀疑通过非标准端口上的 SSH 可能会被阻止，或者需要使用 http/https 访问 Web，您可以配置 git-review 使用 https 端点而不是 ssh，如 Infrastructure 手册中所述。

Python¶

如果您看到此错误

/usr/bin/env: python: No such file or directory

您的 Python 环境未正确设置。请参阅您操作系统的 Python 文档。

i18n¶

如果您看到此错误

$ git review -s
Problems encountered installing commit-msg hook
The following command failed with exit code 1
   "scp  :hooks/commit-msg .git/hooks/commit-msg"
-----------------------
.git/hooks/commit-msg: No such file or directory
-----------------------

您可能将 LANGUAGE 变量设置为其他值，而不是 C。请尝试使用

$ LANG=C LANGUAGE=C git review -s

首次贡献者

首次贡献者¶

准备贡献¶

设置文本编辑器¶

设置 git 和 git-review¶

设置 SSH¶

设置仓库¶

查找错误¶

提交更改¶

响应请求¶

故障排除设置¶

git 和 git review¶

网络¶

Python¶

i18n¶

文档贡献者指南

页面内容