文档工具和工作流
Grafana 将文档作为代码进行管理，并使用 Git 存储在版本控制中。要了解更多 Git 的使用方法，请参阅使用 Git。
使用 Git
尽管不同仓库的贡献更改流程有所不同，但在 Grafana 有一套基本一致的工作流。
创建本地仓库
仅在首次向 GitHub 仓库贡献时需要创建本地仓库。要从远程仓库创建本地仓库，可以使用以下任一方式：
git clone <URL>: 其中<URL>是仓库的 URL。要了解更多信息，请参阅使用 Git 克隆。
gh repo clone <REPOSITORY>: 其中<REPOSITORY>是仓库的名称。例如，grafana/writers-toolkit要了解更多信息，请参阅使用 GitHub CLI 克隆。
使用 GitHub CLI 克隆
您必须首先安装 GitHub CLI 并使用 GitHub 进行身份验证。要安装 GitHub CLI 工具，请参阅安装。要使用 GitHub 进行身份验证，请参阅使用 GitHub 进行身份验证。
要克隆 grafana/writers-toolkit 仓库，请切换到包含您仓库的目录并运行
gh repo clone grafana/writers-toolkit输出类似于以下内容
Cloning into 'writers-toolkit'...
remote: Enumerating objects: 5599, done.
remote: Counting objects: 100% (1493/1493), done.
remote: Compressing objects: 100% (682/682), done.
remote: Total 5599 (delta 1065), reused 1086 (delta 750), pack-reused 4106
Receiving objects: 100% (5599/5599), 8.11 MiB | 4.68 MiB/s, done.
Resolving deltas: 100% (3314/3314), done.然后您可以切换到新创建的目录进入仓库。
cd mimir有关 Grafana 仓库的完整列表，请参阅Grafana 组织的 GitHub 仓库列表。
使用 Git 克隆
克隆使用的 URL 有两种类型：SSH 和 HTTPS。使用 SSH URL 意味着在推送提交时无需提供用户名和个人访问令牌。相反，URL 的身份验证使用 SSH 密钥。要在 GitHub 中设置 SSH 密钥身份验证，请参阅将新的 SSH 密钥添加到您的 GitHub 账户。
Grafana 仓库的 SSH URL 是 git@github.com:grafana/<REPOSITORY>.git。例如，Grafana Mimir 仓库的 SSH URL 是 git@github.com:grafana/mimir.git。
克隆仓库会创建一个目录，其中包含一个 Git 仓库和一个名为 origin 的配置好的 Git 远程，该远程指向远程仓库。
例如，要克隆 Grafana Mimir 仓库
git clone git@github.com:grafana/mimir.git输出类似于以下内容
Cloning into 'mimir'...
remote: Enumerating objects: 111551, done.
remote: Counting objects: 100% (12447/12447), done.
remote: Compressing objects: 100% (3830/3830), done.
remote: Total 111551 (delta 9389), reused 10865 (delta 8511), pack-reused 99104
Receiving objects: 100% (111551/111551), 101.82 MiB | 3.50 MiB/s, done.
Resolving deltas: 100% (73091/73091), done.然后您可以切换到新创建的目录进入仓库。
cd mimir有关 Grafana 仓库的完整列表，请参阅Grafana 组织的 GitHub 仓库列表。
从远程仓库下载更新的引用
在向仓库贡献更改之前，拥有远程引用的最新副本非常重要，以确保您的更改不过时。要从远程仓库获取更新的引用，请使用 git fetch。
git fetch如果没有更新，该命令不会产生输出。如果有更新，输出类似于以下内容
remote: Enumerating objects: 547, done.
remote: Counting objects: 100% (488/488), done.
remote: Compressing objects: 100% (128/128), done.
remote: Total 373 (delta 280), reused 328 (delta 242), pack-reused 0
Receiving objects: 100% (373/373), 156.38 KiB | 1.38 MiB/s, done.
Resolving deltas: 100% (280/280), completed with 79 local objects.
From github.com:grafana/mimir
659af75c3..321d1ae89 main -> origin/main
* [new branch] threaded-reader -> origin/threaded-reader从默认远程分支创建分支
按照惯例，GitHub 中的远程仓库是仓库历史的真实来源。仓库的默认分支通常称为 main，偶尔也称为 master。Grafana 偏好使用包容性语言，因此 main 是首选名称。
从 GitHub 中的远程仓库获取更改后，创建本地分支来提交您的更改。在您自己的分支上工作可以分离和隔离您的更改，以便它们在合并到默认分支之前可以进行评审。
分支名称应该是唯一的。
要从名为 main 的远程分支创建名为 my-branch 的分支
git checkout -b my-branch origin/main输出如下
branch 'my-branch' set up to track 'origin/main'.
Switched to a new branch 'my-branch'您现在位于新的本地分支上，可以开始提交更改。这意味着您现在正在您创建的分支上工作，以反映您计划进行的更改，并且可以使用此分支自由开发您的内容并测试不同的布局、方法或结构。
要检查您正在哪个分支上工作，请使用 git branch。该命令会输出本地分支列表，当前分支用星号 * 标记。例如
git branch输出类似于以下内容
* my-branch
main输出表明您位于 my-branch 分支上，并且还有一个名为 main 的本地分支。
或者，您可以使用 git status 来检查当前分支并了解分支的状态。
注意
git status依赖于您的本地仓库拥有来自远程仓库的最新引用。在
git status之前运行git fetch以获得最准确的状态。
要了解 git status 的输出，请参阅Git - git-status 文档。
检出 PR 分支
要检出 PR 分支，请使用 GitHub CLI (gh) 工具。要安装 GitHub CLI 工具，请参阅安装。
它从远程仓库获取并配置您仓库中的本地分支来跟踪该远程分支。
在您本地检出的仓库目录中运行该命令，以检出贡献者的 PR。将 <PR NUMBER> 替换为 Pull Request 的编号。
gh pr checkout <PR NUMBER>从 Fork 检出 PR 分支
Fork 是一个与原始*上游*仓库共享代码和可见性设置的仓库。
要了解更多信息，请参阅关于 Fork。
要从 Fork 检出 PR 分支，请使用 GitHub CLI (gh) 工具。要安装 GitHub CLI 工具，请参阅安装。
它从 Fork 远程仓库获取并配置您仓库中的本地分支来跟踪该 Fork 中的远程分支。
在您本地检出的上游仓库目录中运行该命令，以检出贡献者的 PR。将 <PR NUMBER> 替换为 Pull Request 的编号。
gh pr checkout <PR NUMBER>输出类似于以下内容
remote: Enumerating objects: 14, done.
remote: Counting objects: 100% (9/9), done.
remote: Compressing objects: 100% (2/2), done.
remote: Total 14 (delta 7), reused 7 (delta 7), pack-reused 5
Unpacking objects: 100% (14/14), 7.68 KiB | 1.10 MiB/s, done.
From github.com:grafana/grafana
* [new ref] refs/pull/76925/head -> patch-2
Switched to branch 'patch-2'GitHub CLI 工具会自动配置远程跟踪分支，以便您可以从 Fork 分支进行 Push 和 Pull。
注意
只有在 PR 作者已启用 允许维护者编辑和访问密钥或允许维护者编辑时，您才能 Push 到 Fork。
要启用维护者编辑，请参阅在现有 Pull Request 上启用仓库维护者权限。
将更改提交到您的分支
提交更改有两个步骤：暂存和提交。您可以暂存整个文件和目录，也可以暂存文件内的单独区域。
暂存文件和目录
要暂存整个文件或目录，请使用 git add <PATH...>。例如，要在当前工作目录中暂存 updated.md 文件
git add updated.md暂存与当前更改相关的所有文件。
暂存文件内的单独区域
差异块（Diff hunk）是文件中的单独差异区域。每个差异块显示文件在不同版本之间的一个差异区域。您可以使用 git add -p 交互式地暂存差异块。git 会向您展示您所做的每个更改的差异块，并询问您是否要暂存它。回答提示符 y 暂存该块。回答提示符 n 跳过暂存该块。回答提示符 q 跳过暂存该块和任何剩余的块。回答提示符 a 暂存该块和任何剩余的块。
使用提示符，暂存与当前更改相关的所有块。
暂存更改后，您可以使用 git commit -s 提交它们。git 会打开您的文本编辑器，您可以在其中键入提交消息。
注意
-s标志会向您的提交添加Signed-off-by消息，表明您同意发布在 https://developercertificate.org/ 的条款，适用于该特定提交。这是许多仓库的要求。
消息的第一行是主题。提交主题应该具有描述性且简洁，通常以祈使句、现在时态编写。要提供额外信息，请在主题后留一个空行并编写提交正文。例如
Use US English spellings
US English is preferred by our technical documentation style-guide.
For more information, refer to https://github.com/grafana/technical-documentation/tree/main/docs/sources/style-guide.保存并关闭 Git 打开的文件以完成提交。
对于只需编写主题的小改动，可以使用 -m 选项提供消息，而无需调用编辑器。例如
git commit -s -m "Use US English spellings"您可以多次提供 -m 选项。Git 使用第一个选项的参数作为提交主题。其他选项的参数成为提交正文段落。
将更改 Push 到远程仓库
将更改 Push 到远程仓库允许其他人查看您的提交并进行评审。这也是将您的更改合并到默认分支的第一步。
使用 git push Push 您的更改。
要将您的本地分支 my-branch Push 到同名的远程分支
git push -u origin my-branch输出类似于以下内容
Enumerating objects: 14, done.
Counting objects: 100% (14/14), done.
Delta compression using up to 8 threads
Compressing objects: 100% (8/8), done.
Writing objects: 100% (10/10), 3.34 KiB | 3.34 MiB/s, done.
Total 10 (delta 5), reused 0 (delta 0), pack-reused 0
remote: Resolving deltas: 100% (5/5), completed with 3 local objects.
remote:
remote: Create a pull request for 'my-branch' on GitHub by visiting:
remote: https://github.com/grafana/technical-documentation/pull/new/my-branch
remote:
To github.com:grafana/technical-documentation.git
* [new branch] HEAD -> my-branch
branch 'my-branch' set up to track 'origin/my-branch'.GitHub 的响应中包含一个链接，用于为您的远程分支打开 Pull Request。点击该链接打开 GitHub，然后点击屏幕左上角的绿色按钮，为评审者打开 Pull Request。在这里，您还可以在较大的文本框中编辑标题和更多细节，并通过点击评审者并输入评审者的 GitHub 用户名来添加评审者。
强制 Push 更改
如果您重写本地历史，或者您的本地分支由于其他原因与远程分支发生分歧，您可能需要强制远程仓库接受您的更改。
在这种情况下，优先使用 --force-with-lease 而不是 --force，前者仅在您的本地分支是最新的情况下才覆盖远程分支。这样，您就不会意外覆盖其他人 Push 的您不知道的提交。要了解更多信息，请参阅 man git-push 中该选项的文档。
合并 Main 分支的更改
Git 和 GitHub 允许许多作者在您进行操作的同时创建和合并 Pull Request。从您创建分支到准备合并 Pull Request 期间，默认分支可能已经发生了显著变化，甚至与您的分支产生了冲突。
如果更改不冲突，您可以使用 Git 将对默认分支的更改合并到您的分支中，而无需进行任何额外更改。
提示
只要 Pull Request 显示允许维护者编辑此 Pull Request，您也可以更新贡献者的分支。
要这样做，首先使用以下任一方式检出他们的 Pull Request：检出 PR 分支或从 Fork 检出 PR 分支。
首先，Fetch 所有分支和远程的更改
git fetch --all在您的分支上，合并默认分支，将其更改应用到您的分支
git merge main如果没有可应用的更改，Git 会确认。输出类似于以下内容
Already up to date.否则，如果成功，Git 会输出它应用于您分支的更改：输出类似于以下内容
Removing public/app/plugins/panel/geomap/utils/view.ts
...
Auto-merging .github/CODEOWNERS
Merge made by the 'recursive' strategy.
.betterer.results | 142 +--
.drone.yml | 351 ++++++-
.github/CODEOWNERS | 3 +
...解决冲突
当源分支和您的分支直接冲突时，GitHub 和 Git 都会向您发出警告。
如果您的分支与目标分支冲突，GitHub 会在 Pull Request 中通知您。对于不太复杂的冲突，GitHub 允许您使用 Web 编辑器解决。要了解更多信息，请参阅关于合并冲突。
如果冲突太复杂无法在 Web 编辑器中解决，GitHub 会指导您在命令行上解决。
如果在尝试将目标分支合并到您的分支时发生冲突，Git 也会告诉您哪些文件存在冲突
Auto-merging .github/CODEOWNERS
CONFLICT (content): Merge conflict in .github/CODEOWNERS
Automatic merge failed; fix conflicts and then commit the result.GitHub 提供了详细的跨平台说明，指导您如何在命令行上使用 Git 解决合并冲突。要了解更多信息，请参阅使用命令行解决合并冲突。
将 Fork 与其上游仓库同步
要将 Fork 与其上游仓库同步，请切换到您仓库检出的目录并运行
gh repo sync <FORK REPOSITORY>有关命令选项的更多信息，请参阅gh repo sync 文档。
使用 GitHub CLI
GitHub CLI 简化了使用 GitHub 仓库时的一些 Git 工作流。
安装 GitHub CLI
要安装 GitHub CLI 工具，请参阅安装。
使用 GitHub 进行身份验证
安装 GitHub CLI 后，您必须使用 GitHub 进行身份验证。要使用 GitHub 进行身份验证，请运行 gh auth login 并按照交互式设置进行操作。
您也可以使用 gh 作为 Git 的凭据助手。要使用 gh 作为 Git 的凭据助手，请运行 gh auth setup-git。要了解更多 Git 凭据助手的信息，请参阅Git - gitcredentials 文档。