提交内容

若要贡献新的或改进现有的文档，请提交一个 pull request：

• 如果你的改动较小，或你不熟悉 Git，请参见使用 GitHub 了解如何编辑页面。
• 否则，请参见从本地 Fork 开始工作了解如何在本地开发环境中进行更改。

下图展示了如何贡献新文档内容。

flowchart LR
    subgraph first[如何贡献]
    direction TB
       T[ ] -.-
       B[在 GitHub 中 Fork 仓库] --- C[用 Markdown 编写文档<br>并用 Hugo 构建站点]
       C --- D[将源文件推送到 Fork]
       D --- E[创建一个 PR]
       E --- F[签署 CNCF CLA]
    end

classDef grey fill:#dddddd,stroke:#ffffff,stroke-width:px,color:#000000, font-size:15px;
classDef white fill:#ffffff,stroke:#000,stroke-width:px,color:#000,font-weight:bold
classDef spacewhite fill:#ffffff,stroke:#fff,stroke-width:0px,color:#000
class A,B,C,D,E,F,G,H grey
class S,T spacewhite
class first,second white

图 1. 贡献新内容

使用 GitHub

从浏览器编辑并提交更改

如果你对 Git 工作流不太熟悉，可以使用以下更简单的方法来准备并提交新的 PR。 图 2 概述了操作步骤，下面是具体说明。

flowchart LR
A([fa:fa-user 新贡献者]) --- id1[(open-telemetry/opentelemetry.io<br>GitHub)]
subgraph tasks[使用 GitHub 更改]
direction TB
    0[ ] -.-
    1[1\. 编辑此页面] --> 2[2\. 使用 GitHub 的 Markdown 编辑器进行更改]
    2 --> 3[3\. 填写 Propose file change 表单]
end
subgraph tasks2[ ]
direction TB
4[4\. 选择 Propose file change] --> 5[5\. 选择 Create pull request] --> 6[6\. 填写 Open a pull request]
6 --> 7[7\. 选择 Create pull request]
end

id1 --> tasks --> tasks2

classDef grey fill:#dddddd,stroke:#ffffff,stroke-width:px,color:#000000, font-size:15px;
classDef white fill:#ffffff,stroke:#000,stroke-width:px,color:#000,font-weight:bold
classDef k8s fill:#326ce5,stroke:#fff,stroke-width:1px,color:#fff;
classDef spacewhite fill:#ffffff,stroke:#fff,stroke-width:0px,color:#000
class A,1,2,3,4,5,6,7 grey
class 0 spacewhite
class tasks,tasks2 white
class id1 k8s

图 2. 使用 GitHub 提交 PR 的步骤

1. 在你看到问题的页面中，点击右侧导航栏的 Edit this page。
2. 如果你不是该项目的成员，GitHub 会提示你 Fork 仓库，点击 Fork this repository。
3. 在 GitHub 编辑器中进行更改。
4. 填写 Propose file change 表单。
5. 点击 Propose file change。
6. 点击 Create pull request。
7. 在 Open a pull request 页面中填写说明，帮助审阅者理解你的更改。
8. 点击 Create pull request。

在合并 PR 之前，OpenTelemetry 社区成员会对其进行审核并批准。

如果审阅者要求你进行更改：

1. 前往 Files changed 标签页。
2. 点击铅笔图标编辑 PR 中更改的文件。
3. 按要求修改。如果有代码建议，可直接应用。
4. 提交更改。

审阅完成后，审阅者将合并你的 PR，更改将在几分钟后上线。

修复 PR 检查失败

提交 PR 后，GitHub 会运行一些构建检查。某些失败（如格式问题）可以自动修复。

在你的 PR 中添加以下评论：

/fix:all

这将触发 OpenTelemetry 机器人尝试修复构建问题。你也可以使用以下命令修复特定问题：

fix:dict
fix:expired
fix:filenames
fix:format
fix:htmltest-config
fix:i18n
fix:markdown
fix:refcache
fix:submodule
fix:text

npm run -s '_list:fix:*'

本地工作流程

如果你熟悉 Git，或你的更改大于几行，建议从本地 Fork 开始工作。

请确保你已在本地安装 git。你也可以使用 Git 图形界面工具。

flowchart LR
1[Fork open-telemetry/opentelemetry<br>仓库] --> 2[本地克隆并设置 upstream]
subgraph changes[你的更改]
direction TB
S[ ] -.-
3[创建分支<br>例如：my_new_branch] --> 3a[用文本编辑器进行修改] --> 4["使用 Hugo 本地预览更改<br>(localhost:1313)"]
end
subgraph changes2[提交/推送]
direction TB
T[ ] -.-
5[提交更改] --> 6[将提交推送到<br>origin/my_new_branch]
end

2 --> changes --> changes2

classDef grey fill:#dddddd,stroke:#ffffff,stroke-width:px,color:#000000, font-size:15px;
classDef white fill:#ffffff,stroke:#000,stroke-width:px,color:#000,font-weight:bold
classDef k8s fill:#326ce5,stroke:#fff,stroke-width:1px,color:#fff;
classDef spacewhite fill:#ffffff,stroke:#fff,stroke-width:0px,color:#000
class 1,2,3,3a,4,5,6 grey
class S,T spacewhite
class changes,changes2 white

图 3. 从本地 Fork 修改内容

Fork 仓库

1. 打开 opentelemetry.io 仓库。
2. 点击 Fork。

克隆并设置 Upstream

1. 在终端中克隆你的 Fork 并安装依赖：

   git clone git@github.com:<你的 GitHub 用户名>/opentelemetry.io.git
   cd opentelemetry.io
   npm install
   

2. 设置 open-telemetry/opentelemetry.io 为 upstream：

   git remote add upstream https://github.com/open-telemetry/opentelemetry.io.git
   

3. 验证 origin 和 upstream：

   git remote -v
   

   示例输出：

   origin	git@github.com:<你的用户名>/opentelemetry.io.git (fetch)
   origin	git@github.com:<你的用户名>/opentelemetry.io.git (push)
   upstream	https://github.com/open-telemetry/opentelemetry.io.git (fetch)
   upstream	https://github.com/open-telemetry/opentelemetry.io.git (push)
   

4. 拉取 origin 和 upstream 的更新：

   git fetch origin
   git fetch upstream
   

   这可以确保你在开始修改之前，本地仓库是最新的。请定期将 upstream 的更改推送到 origin，以保持你的 Fork 与上游仓库同步。

创建分支

1. 基于 upstream/main 创建新分支：

   git checkout -b <my_new_branch> upstream/main
   

2. 使用代码或文本编辑器进行修改。

使用 git status 查看你更改了哪些文件。

提交更改

当你准备提交 PR 时，请提交你的更改。

1. 在本地仓库中，检查你需要提交的文件：

   git status
   

   输出类似于：

   On branch <my_new_branch>
   Your branch is up to date with 'origin/<my_new_branch>'.
   
   Changes not staged for commit:
   (use "git add <file>..." to update what will be committed)
   (use "git checkout -- <file>..." to discard changes in working directory)
   
   modified:   content/en/docs/file-you-are-editing.md
   
   no changes added to commit (use "git add" and/or "git commit -a")
   

2. 将 Changes not staged for commit 中列出的文件添加到提交中：

   git add <你的文件名>
   

   对每个文件重复此操作。

3. 添加完所有文件后，创建一次提交：

   git commit -m "你的提交信息"
   

4. 将你的本地分支及其新提交推送到远程 Fork：

   git push origin <新分支>
   

5. 更改推送完成后，GitHub 会提示你可以创建一个 PR。

创建新的 PR

图 4 展示了如何从你的 Fork 仓库向 opentelemetry.io 提交一个 PR 的步骤。

flowchart LR
subgraph first[ ]
direction TB
1[1\. 打开 opentelemetry.io 仓库] --> 2[2\. 选择 New Pull Request]
2 --> 3[3\. 选择 compare across forks]
3 --> 4[4\. 从 head repository 下拉中选择你的 Fork]
end
subgraph second [ ]
direction TB
5[5\. 从 compare 下拉中选择你的分支] --> 6[6\. 点击 Create Pull Request]
6 --> 7[7\. 填写 PR 描述]
7 --> 8[8\. 点击 Create pull request]
end

first --> second

classDef grey fill:#dddddd,stroke:#ffffff,stroke-width:px,color:#000000, font-size:15px;
classDef white fill:#ffffff,stroke:#000,stroke-width:px,color:#000,font-weight:bold
class 1,2,3,4,5,6,7,8 grey
class first,second white

图 4：从你的 Fork 仓库向 opentelemetry.io 提交 PR 的步骤

1. 在浏览器中，前往 opentelemetry.io 仓库。

2. 点击 New Pull Request。

3. 点击 compare across forks。

4. 在 head repository 下拉菜单中，选择你的 fork 仓库。

5. 在 compare 下拉菜单中，选择你要提交的分支。

6. 点击 Create Pull Request。

7. 添加你的PR的描述信息：

   • Title（50 个字符以内）：简要说明变更目的。
   • Description：更详细地说明你的变更内容。
     • 如果该变更关联某个 GitHub Issue，在描述中加入 Fixes #12345 或 Closes #12345， 这样 GitHub 在合并 PR 后会自动关闭对应 issue。
     • 如果你有任何具体问题需要建议，可以在描述中写出你希望评审者关注的问题。

8. 点击 Create pull request 按钮。

你的 PR 将在 Pull requests 页面中显示。

提交 PR 后，GitHub 会自动运行测试，并尝试使用 Netlify 部署预览版本：

• 如果 Netlify 构建失败，点击 Details 查看更多信息。
• 如果 Netlify 构建成功，点击 Details 可以打开已应用你改动的 OpenTelemetry 网站预览版本。评审者会通过该预览来查看你的更改效果。

其他检查项也可能失败。详见所有 PR 检查项列表。

修复问题

在提交更改到仓库之前，请运行以下命令，并完成以下两项操作：

1. 处理脚本报告的所有问题；
2. 提交脚本修改过的所有文件：

npm run test-and-fix

如果你希望分开进行检查和修复，可以分别运行以下命令：

npm run test    # 仅检查文件，不会修改任何内容
npm run fix:all # 可能会自动修改文件

要查看所有可用的 NPM 脚本，请运行：

npm run

更多关于拉取请求检查项及其自动修复方法的信息，请参见 PR 检查项。

预览更改

本地预览可以帮助你在提交 PR 前发现构建或格式问题。

启动本地预览：

npm run serve

浏览器访问 http://localhost:1313 查看预览。

要停止本地服务，在终端按下 Ctrl+C。

站点部署和 PR 预览

当你提交 PR 时，Netlify 会创建一个部署预览，方便你查看所做的更改。 一旦你的 PR 被合并，Netlify 会将更新后的网站部署到生产服务器。

注意：PR 预览包含草稿页面，但生产环境构建不包含草稿页面。

要查看部署日志等信息，请访问项目的仪表盘 —— 需要登录 Netlify。

PR 提交流程建议

为确保审核流程顺利进行，请注意以下几点：

• 除非是微小更改，否则请 使用 Fork 工作流。
• 不要直接使用 Fork 的 main 分支，请新建分支。
• 确保你允许维护者对 PR 分支进行更改。

来自审阅者的更改

有时，审阅者会直接向你的 PR 提交更改。在你进行其他修改之前，需先获取这些提交。

1. 从你的远程 Fork 获取提交并将其变基到当前工作分支：

   git fetch origin
   git rebase origin/<你的分支名>
   

2. 变基完成后，将新更改强制推送到你的 Fork：

   git push --force-with-lease origin <你的分支名>
   

你也可以在 GitHub 的用户界面中解决合并冲突。

合并冲突与变基

如果其他贡献者在另一个 PR 中修改了同一个文件，就可能会产生合并冲突。 你必须在自己的 PR 中解决所有的合并冲突。

1. 更新你的 Fork，并对本地分支执行变基：

   git fetch origin
   git rebase origin/<你的分支名>
   

   然后强制推送变基后的更改到你的 Fork：

   git push --force-with-lease origin <你的分支名>
   

2. 从 open-telemetry/opentelemetry.io 项目的 upstream/main 获取更新，并对你的分支执行变基：

   git fetch upstream
   git rebase upstream/main
   

3. 检查变基后的状态：

   git status
   

   这会显示哪些文件存在冲突。

4. 打开每个有冲突的文件，查找冲突标记：>>>、<<< 和 ===。解决冲突后删除这些标记。

   详情请参见 Git 合并冲突的表现形式。

5. 将已解决的文件加入暂存区：

   git add <文件名>
   

6. 继续变基过程：

   git rebase --continue
   

7. 如有必要，重复第 2 至第 5 步。

   当所有提交都已成功应用后，git status 命令会显示变基已完成。

8. 强制推送你的分支到 Fork：

   git push --force-with-lease origin <你的分支名>
   

   现在，PR 将不再显示冲突。

合并要求

PR 必须满足以下条件才能被合并：

• 所有由批准者、维护者、技术委员会成员或主题专家所做的审查都显示为 “Approved”（已批准）。
• 没有未解决的评论对话。
• 至少有一位批准者已批准。
• 没有失败的 PR 检查。
• PR 分支与目标分支保持最新。
• 文档页面的更改不应跨多个语言。

重要提示

不必过于担心失败的 PR 检查。社区成员会协助你修复这些问题，可能会提供修复方法或直接帮你修复。