Submitting content

了解如何使用 GitHub 界面或从本地 fork 提交新内容或已更改的内容。

要贡献新文档或改进现有文档，请提交 拉取请求 (PR)

  • 如果您的更改很小，或者您不熟悉 Git，请参阅 使用 GitHub 了解如何编辑页面。
  • 否则，请参阅 从本地 fork 开发 了解如何在本地开发环境中进行更改。

生成式 AI 贡献政策

允许使用生成式 AI，但 **您有责任** **审阅和验证** 所有 AI 生成的内容 — 如果您不理解，请不要提交！

有关详细信息，请参阅我们的 生成式 AI 贡献政策。

如何贡献

下图说明了如何贡献新文档。

flowchart LR
    subgraph first[How to contribute]
    direction TB
       T[ ] -.-
       B[Fork the repo in GitHub] --- C[Write docs in markdown<br>and build site with Hugo]
       C --- D[Push source to the fork]
       D --- E[Open a pull request]
       E --- F[Sign the <a href="../prerequisites/#cla">CNCF CLA</a>]
    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 New<br>Contributor]) --- id1[(open-telemetry/opentelemetry.io<br>GitHub)]
subgraph tasks[Changes using GitHub]
direction TB
    0[ ] -.-
    1[1\. Edit this page] --> 2[2\. Use GitHub markdown<br>editor to make changes]
    2 --> 3[3\. Fill in Propose file change]

end
subgraph tasks2[ ]
direction TB
4[4\. Select Propose file change] --> 5[5\. Select Create pull request] --> 6[6\. Fill in Open a pull request]
6 --> 7[7\. Select 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. 在您看到问题的页面上，选择右侧导航面板中的编辑此页面选项。

  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（创建拉取请求）。

在合并拉取请求之前，OpenTelemetry 社区成员会对其进行审阅和批准。

如果审阅者要求您进行更改

  1. 转到Files changed（已更改文件）选项卡。
  2. 选择 PR 更改的任何文件上的铅笔（编辑）图标。
  3. 进行请求的更改。如果有代码建议，请应用它。
  4. 提交更改。

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

修复 PR 检查失败

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

在您的 PR 中添加以下评论

/fix:all

这将触发 OpenTelemetry bot 尝试修复构建问题。或者，您可以发出以下修复命令之一来解决特定失败

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

本地开发

如果您对 Git 更熟悉，或者您的更改比几行代码要多，请从本地 fork 进行开发。

确保您的计算机上已安装了 git。您也可以使用 Git 的用户界面。

图 3 显示了从本地 fork 开发时要遵循的步骤。每个步骤的详细信息如下。

flowchart LR
1[Fork the open-telemetry/opentelemetry<br>repository] --> 2[Create local clone<br>and set upstream]
subgraph changes[Your changes]
direction TB
S[ ] -.-
3[Create a branch<br>example: my_new_branch] --> 3a[Make changes using<br>a text editor] --> 4["Preview your changes<br>locally using Hugo<br>(localhost:1313)"]
end
subgraph changes2[Commit / Push]
direction TB
T[ ] -.-
5[Commit your changes] --> 6[Push commit to<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。

克隆并设置上游

  1. 在终端窗口中，克隆您的 fork 并安装所需的环境

    git clone git@github.com:<your_github_username>/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:<your_github_username>/opentelemetry.io.git (fetch)
origin	git@github.com:<your_github_username>/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. 从您的 fork 的 origin/main 和 open-telemetry/opentelemetry.io 的 upstream/main 中获取提交

    git fetch origin
git fetch upstream

    这可确保在开始进行更改之前，您的本地仓库是最新的。定期将上游的更改推送到 origin，以使您的 fork 与上游保持同步。

创建分支

  1. 创建一个新分支。此示例假定基础分支是 upstream/main

    git checkout -b <my_new_branch> upstream/main

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

随时使用 git status 命令查看您更改了哪些文件。

提交你的更改

当您准备好提交拉取请求时，请提交您的更改。

  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 <your_file_name>

    对每个文件重复此操作。

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

    git commit -m "Your commit message"

  4. 将您的本地分支及其新提交推送到您的远程 fork

    git push origin <my_new_branch>

  5. 推送更改后，GitHub 会通知您可以创建 PR。

打开新的 PR

图 4 显示了从您的 fork 打开 PR 到 opentelemetry.io 的步骤。

flowchart LR
subgraph first[ ]
direction TB
1[1\. Go to opentelemetry.io repository] --> 2[2\. Select New Pull Request]
2 --> 3[3\. Select compare across forks]
3 --> 4[4\. Select your fork from<br>head repository drop-down menu]
end
subgraph second [ ]
direction TB
5[5\. Select your branch from<br>the compare drop-down menu] --> 6[6\. Select Create Pull Request]
6 --> 7[7\. Add a description<br>to your PR]
7 --> 8[8\. Select 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 打开 PR 到 opentelemetry.io 的步骤。

  1. 在浏览器中，转到 opentelemetry.io 仓库。

  2. 选择New Pull Request（新建拉取请求）。

  3. 选择compare across forks（跨 fork 比较）。

  4. 在head repository（目标仓库）下拉菜单中，选择您的 fork。

  5. 在compare（比较）下拉菜单中，选择您的分支。

  6. 选择Create Pull Request（创建拉取请求）。

  7. 为您的拉取请求添加描述

    • Title（标题）（50 个字符以内）：总结更改的意图。
    • Description（描述）：更详细地描述更改。
      • 如果存在相关的 GitHub 问题，请在描述中包含 Fixes #12345 或 Closes #12345，以便 GitHub 自动化在合并 PR 后关闭提及的问题。如果存在其他相关 PR，也请链接它们。
      • 如果您想就特定事项征求意见，请在描述中包含您希望审阅者考虑的任何问题。

  8. 选择Create pull request（创建拉取请求）按钮。

您的拉取请求可以在 Pull requests（拉取请求）中找到。

打开 PR 后，GitHub 会运行自动化测试并尝试使用 Netlify 部署预览。

  • 如果 Netlify 构建失败，请选择Details（详细信息）以获取更多信息。
  • 如果 Netlify 构建成功，请选择Details（详细信息）以打开 OpenTelemetry 网站的暂存版本，其中包含您的更改。这是审阅者检查您更改的方式。

其他检查也可能失败。请参阅 所有 PR 检查列表。

修复问题

在将更改提交到仓库之前，运行以下命令并（i）解决所有报告的问题，（ii）提交脚本更改的任何文件

npm run test-and-fix

要单独测试和修复您文件中的所有问题，请运行

npm run test    # Checks but does not update any files
npm run fix:all # May update files

要列出可用的 NPM 脚本，请运行 npm run。有关拉取请求检查的更多信息以及如何自动修复错误，请参阅 PR 检查。

预览你的更改

在推送更改或打开拉取请求之前，请在本地预览您的更改。预览可以帮助您发现构建错误或 Markdown 格式问题。

要使用 Hugo 在本地构建和提供网站，请运行以下命令

npm run serve

在网络浏览器中导航到 https://:1313 以查看本地预览。Hugo 会监视更改并按需重新构建网站。

要停止本地 Hugo 实例，请返回终端并键入 Ctrl+C，或关闭终端窗口。

网站部署和 PR 预览

如果您提交了 PR，Netlify 会创建一个 部署预览，以便您可以审阅您的更改。一旦您的 PR 被合并，Netlify 就会将更新后的网站部署到生产服务器。

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

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

PR 指南

在 PR 合并之前，有时需要经过几次审阅-编辑迭代。为了帮助我们和您自己尽可能轻松地完成此过程，我们要求您遵守以下规定

  • 如果您的 PR 不是一个快速修复，那么请从 fork 进行开发：点击仓库顶部的 Fork 按钮，并在本地克隆 fork。当您准备好后，向主仓库发起 PR。
  • 不要从 fork 的 main 分支进行开发，而是创建一个专门用于 PR 的分支。
  • 确保允许审阅者对您的拉取请求进行更改。

审阅者的更改

有时审阅者会提交到您的 PR。在进行任何其他更改之前，请先获取这些提交。

  1. 从您的远程 fork 获取提交并变基您的工作分支

    git fetch origin
git rebase origin/<your-branch-name>

  2. 变基后，强制将新更改推送到您的 fork

    git push --force-with-lease origin <your-branch-name>

您也可以从 GitHub UI 解决合并冲突。

合并冲突和变基

如果另一个贡献者在另一个 PR 中提交了对同一文件的更改，则可能会产生合并冲突。您必须解决 PR 中的所有合并冲突。

  1. 更新您的 fork 并变基您的本地分支

    git fetch origin
git rebase origin/<your-branch-name>

    然后强制将更改推送到您的 fork

    git push --force-with-lease origin <your-branch-name>

  2. 从 open-telemetry/opentelemetry.io 的 upstream/main 获取更改并变基您的分支

    git fetch upstream
git rebase upstream/main

  3. 检查变基结果

    git status

    这会导致许多文件被标记为已冲突。

  4. 打开每个冲突文件并查找冲突标记：>>>、<<< 和 ===。解决冲突并删除冲突标记。

    有关更多信息，请参阅 冲突的呈现方式。

  5. 将文件添加到更改集

    git add <filename>

  6. 继续变基

    git rebase --continue

  7. 根据需要重复步骤 2 到 5。

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

  8. 强制将分支推送到您的 fork

    git push --force-with-lease origin <your-branch-name>

    拉取请求不再显示任何冲突。

合并要求

当拉取请求符合以下标准时，便会被合并

  • 所有批准者、维护者、技术委员会成员或主题专家进行的审阅状态均为“已批准”。
  • 没有未解决的对话。
  • 至少由一名批准者批准。
  • 没有失败的 PR 检查。
  • PR 分支已与基础分支同步。
  • 文档页面更改 不跨越本地化版本。

重要提示

不要过于担心失败的 PR 检查。社区成员会通过提供如何修复的说明或亲自为您修复来帮助您。


最后修改于 2025 年 12 月 18 日：为首次贡献者添加 genai 注释 (#8659) (368ef6c1)