主要或持续更改的 GitHub 参与工作流GitHub contribution workflow for major or long-running changes

重要

发布到 docs.microsoft.com 的所有存储库均遵循 Microsoft 开放源代码行为准则.NET 基础行为准则All repositories that publish to docs.microsoft.com have adopted either the Microsoft Open Source Code of Conduct or the .NET Foundation Code of Conduct. 有关详细信息,请参阅行为准则常见问题解答For more information, see the Code of Conduct FAQ. 或如有任何疑问或意见,请联系 opencode@microsoft.comconduct@dotnetfoundation.orgOr contact opencode@microsoft.com, or conduct@dotnetfoundation.org with any questions or comments.

docs.microsoft.com 使用条款适用于对公共存储库中文档和代码示例所做的小修订和澄清。Minor corrections or clarifications to documentation and code examples in public repositories are covered by the docs.microsoft.com Terms of Use. 如果你不是 Microsoft 的员工,那么新更改或重大更改会在拉取请求中生成一条注释,要求提交一份在线参与许可协议 (CLA)。New or significant changes will generate a comment in the pull request, asking you to submit an online Contribution License Agreement (CLA) if you are not an employee of Microsoft. 在合并拉取请求之前,你需要填写这份在线表单。You will need to complete the online form before your pull request can be merged.

概述Overview

此工作流适合需要进行主要更改的参与者,或者是向存储库频繁供稿的参与者。This workflow is suitable for a contributor who needs to make a major change or will be a frequent contributor to a repository. 频繁供稿的参与者通常会执行不断进行的(即持续)更改(这些更改经过多个构建/验证/暂存周期或跨越多天),然后进行拉取请求签核和合并。Frequent contributors typically have ongoing (long-running) changes, which go through multiple build/validation/staging cycles or span multiple days before pull request sign-off and merge.

这些类型的参与示例包括:Examples of these types of contributions include:

  • 进行大型供稿。Making a large contribution. 例如,可以进行跨越多篇文章且需要作为单个拉取请求中的一个工作单元进行提交和测试的供稿(增补/更改/删除)。For instance, you might make contributions (additions, changes, or deletions) that span multiple articles and need to be committed and tested as one unit of work in a single pull request.
  • 创建和发布新文章,这通常需要更为稳健的本地编辑器。Creating and publishing a new article, which typically requires a more robust local editor.
  • 添加新图像或更新图像,这通常要求同时创建新 media 子目录/图像文件、更新文章中的图像链接、在本地编辑器中预览 markdown 文件来测试图像呈现情况。Adding new images or updating images, which typically requires simultaneous creation of a new media subdirectory, image files, updates to image links in articles, and previewing markdown files in a local editor to test image rendering.
  • 在发布前更新一段时间内的文章。Updating an article over a period of days before you publish. 在这些情况下,通常需要定期集成主分支中的其他更改。In these cases, you typically need to do regular integration of other changes that occur in the master branch. 通过 Git Bash 和本地编辑可更轻松地完成集成。This integration is easier via Git Bash and local editing. 如果通过 GitHub UI 完成合并,还可能丢失编辑内容,请在提交更改前等待一段时间。You also run the risk of losing your edits if you do this via the GitHub UI and wait before you commit the changes.
  • 在拉取请求打开后对同一文章进行持续更新(除非通过 GitHub UI 完成让你感到舒服)。Making continual updates to the same article after a pull request has been opened (unless you are comfortable doing this via the GitHub UI). 使用 GitHub UI 可以对同一文件创建多个显著的拉取请求,它们之间可能相互冲突。Using the GitHub UI has the potential to create multiple outstanding pull requests for the same file, which may conflict with one another.

术语Terminology

在开始之前,让我们回顾一下在此工作流中使用的 Git/GitHub 术语和名字对象。Before you start, let's review some of the Git/GitHub terms and monikers used in this workflow. 不用着急去熟悉它。Don't worry about understanding them now. 只要知道你将对此有所了解,并且在需要验证某个定义时,可以回顾参考本节。Just know that you will be learning about them, and you can refer back to this section when you need to verify a definition.

名称Name 说明Description
分支fork 在表示主 GitHub 存储库的副本时,通常用作名词。Normally used as a noun, when referring to a copy of a main GitHub repository. 实际上,分支只是另一个存储库。In practice, a fork is just another repository. 但是,从某种意义上来说,GitHub 维护至主/父存储库的连接。But it's special in the sense that GitHub maintains a connection back to the main/parent repository. 它有时用作动词,如“必须首先为存储库创建分支”。It's sometimes used as a verb, as in "You must fork the repository first."
远程remote 到远程存储库的命名连接,例如“源”或“上游”远程。A named connection to a remote repository, such as the "origin" or "upstream" remote. Git 称之为“远程源”,因为它们可用于引用托管在另一台计算机上的存储库。Git refers to this as remote because it is used to reference a repository that's hosted on another computer. 在此工作流中,远程始终是一个 GitHub 存储库。In this workflow, a remote is always a GitHub repository.
origin 分配给本地存储库与在其中进行克隆的源存储库之间的连接的名称。The name assigned to the connection between your local repository and the repository from which it was cloned. 在此工作流中,源表示与分支的连接。In this workflow, origin represents the connection to your fork. 它有时用作源存储库本身的一个名字对象,如“请务必将更改推送到源”。It's sometimes used as a moniker for the origin repository itself, as in "Remember to push your changes to origin."
上游upstream 与源远程一样,上游是与另一个存储库的命名连接。Like the origin remote, upstream is a named connection to another repository. 在此工作流中,上游表示本地存储库与在其中创建分支的主存储库之间的连接。In this workflow, upstream represents the connection between your local repository and the main repository, from which your fork was created. 它有时用作上游存储库本身的一个名字对象,如“请务必从上游拉取更改”。It's sometimes used as a moniker for the upstream repository itself, as in "Remember to pull the changes from upstream."

工作流Workflow

重要

如果尚未完成这些步骤,则必须在设置部分完成。If you haven't already, you must complete the steps in the Setup section. 本节内容指导你完成设置 GitHub 帐户、安装 Git Bash 和 Markdown 编辑器、创建分支,并设置本地存储库。This section walks you through setting up your GitHub account, installing Git Bash and a Markdown editor, creating a fork, and setting up your local repository. 如果你不熟悉 Git 和 GitHub 概念(如存储库或分支),请首先回顾一下 Git 和 GitHub 基础知识If you are unfamiliar with Git and GitHub concepts such as a repository or branch, please first review Git and GitHub fundamentals.

在此工作流中,更改在重复循环中传递。In this workflow, changes flow in a repetitive cycle. 从设备的本地存储库开始,它们会传递回 GitHub 分支,进入主 GitHub 存储库,然后在你合并其他参与者提供的更改时再次回到本地。Starting from your device's local repository, they flow back up to your GitHub fork, into the main GitHub repository, and back down locally again as you incorporate changes from other contributors.

使用 GitHub 流Use GitHub flow

回顾 Git 和 GitHub 基础知识,Git 存储库包含一个主分支,以及未集成到主分支的任何正在工作的额外分支。Recall from Git and GitHub fundamentals that a Git repository contains a master branch, plus any additional work-in-progress branches that have not been integrated into master. 每当要引入一组在逻辑上有关联的更改时,最佳做法是创建一个工作分支,用于通过工作流来管理更改 。Whenever you introduce a set of logically related changes, it’s a best practice to create a working branch to manage your changes through the workflow. 这里之所以将其称为工作分支,是因为它是一个会不断迭代/优化更改直至其可集成回主分支的工作空间。We refer to it here as a working branch because it's a workspace to iterate/refine changes, until they can be integrated back into the master branch.

将相关的更改隔离到特定的分支中,可以使你独立地控制和引入这些更改,并将它们定向到发布周期中的特定发布时间。Isolating related changes to a specific branch allows you to control and introduce those changes independently, targeting them to a specific release time in the publishing cycle. 实际上,根据所执行的工作类型,你可以很容易地实现在存储库中使用多个工作分支。In reality, depending on the type of work you do, you can easily end up with several working branches in your repository. 同时使用多个分支很常见,每一项工作都代表一个不同的项目。It's not uncommon to be working on multiple branches at the same time, each representing a different project.

提示

在主分支中进行更改并不是最佳做法 。Making your changes in the master branch is not a good practice. 想象一下,如果你使用主分支为定时功能发布引入一组更改。Imagine that you use the master branch to introduce a set of changes for a timed feature release. 你已完成更改,并等待发布更改。You finish the changes and are waiting to release them. 然后,在过渡期间,你收到一个需要修复某些内容的紧急请求,因此你将在主分支中更改一个文件,然后发布该更改。Then in the interim, you have an urgent request to fix something, so you make the change to a file in the master branch and then publish the change. 在本示例中,你可能无意中发布了修正和更改,而这些内容本应在特定日期发布 。In this example, you inadvertently publish both the fix and the changes that you were holding for release on a specific date.

现在,让我们在本地存储库中创建一个新的工作分支,以获取你所建议的更改。Now let's create a new working branch in your local repository, to capture your proposed changes. 如果已设置 Git Bash(请参阅安装内容创作工具),则可以创建新的分支,并使用一个命令从克隆的存储库中“签出”该分支:If you've setup Git Bash (see Install content authoring tools), you can create a new branch and "checkout" that branch with one command from within your cloned repository:

git checkout -b "branchname"

每个 Git 客户端都不同,因此有关首选客户端,请咨询帮助。Each git client is different, so consult the help for your preferred client. 你可以在 GitHub 流上的 GitHub 指南中查看过程概览。You can see an overview of the process in the GitHub Guide on GitHub flow.

执行更改Making your changes

获得了 Microsoft 存储库的副本(“克隆”)并创建了分支后,现在即可随时使用任何文本或 Markdown 编辑器执行可能对社区有益的任何更改(如安装内容创作工具页面所述)。Now that you have a copy ("clone") of the Microsoft repository and you've created a branch, you're now free to make whatever changes you think would benefit the community using any text or Markdown editor, as outlined on the Install content authoring tools page. 可以在本地保存更改,而无需将更改提交到 Microsoft,准备就绪后再提交即可。You can save your changes locally without needing to submit them to Microsoft until you're ready.

将更改保存到存储库Saving changes to your repository

向作者发送更改之前,必须先将更改保存到 Github 存储库。Before sending your changes to the author, you must first save them to your Github repository. 同样,尽管所有工具都是不同的,但如果使用的是 Git Bash 命令行,则只需几个简单步骤即可完成此操作。Again, while all tools are different, if you're using the Git Bash command line, this can be done in just a few easy steps.

首先,在存储库中,需要暂存所有要提交的更改 。First, from within the repository, you need to stage all of your changes to be commmited. 可以通过执行以下命令完成此操作:This can be done by executing:

git add --all

接下来,需要将保存的更改提交到本地存储库。Next, you need to commit your saved changes to your local repository. 可以通过运行以下命令在 Git Bash 中完成此操作:This can be done in Git Bash by running:

git commit -m "Short Description of Changes Made"

最后,由于此分支在本地计算机上创建,因此需要使 GitHub.com 帐户中的分支知道此分支的存在。Finally, since you created this branch on your local computer, you need to let the fork in your GitHub.com account know about it. 如果使用的是 Git Bash,可通过运行以下命令完成此操作:If you're using Git Bash, this can be done by running:

git push --set-upstream origin <branchname>

大功告成!You've done it! 你的代码现在将在 GitHub 存储库中,并可用于创建拉取请求。Your code is now up in your GitHub repository and ready for you to create a pull request.

提示

尽管更改在推送后即会在个人 GitHub 帐户中可见,但不需要立即提交拉取请求。Even though your changes become visible in your personal GitHub account when you push them, there is no rule that you need to submit a pull request immediately. 如果想要停止并稍后返回进行其他调整,这完全没问题!If you want to come stop and return at a later time to make additional tweaks, that's OK!

需要修复已提交的内容?Need to fix something you submitted? 没问题!No problem! 只需在同一分支中进行更改,然后重新提交并推送即可(无需对同一分支的后续推送设置上游服务器)。Just make your changes in the same branch and then commit and push again (no need to set the upstream server on subsequent pushes of the same branch).

需要执行更多与此分支无关的更改?Got more changes you need to make unrelated to this one? 切换回主分支并使用 Git Bash 签出其他新分支,此过程非常简单,执行以下命令即可:Switch back to the master branch and checkout another fresh branch, Using Git Bash, this is as easy as:

git checkout master
git checkout -b "branchname"

现已位于新分支中,你即将成为主要供稿人。You're now back in a new branch and you're well on your way to being a master contributer.

拉取请求处理Pull request processing

之前的部分介绍了提交建议更改的过程,提交时所用的方式是将建议更改绑定在已添加到目标存储库拉取请求队列的新拉取请求 (PR) 中。The previous section walked you through the process of submitting proposed changes, by bundling them in a new pull request (PR) that is added to the destination repository's PR queue. 拉取请求通过请求将工作分支的更改拉取和合并到其他分支,从而实现 GitHub 的协作模型。A pull request enables GitHub's collaboration model, by asking for the changes from your working branch to be pulled and merged into another branch. 大多数情况下,其他分支就是主存储库中的默认/主分支。In most cases, that other branch is the default/master branch in the main repository.

验证Validation

拉取请求在可以合并到其目标分支前,可能需要通过一个或多个 PR 验证过程。Before your pull request can be merged into its destination branch, it might be required to pass through one or more PR validation processes. 验证过程因建议更改的范围和目标存储库的规则而异。Validation processes can vary depending on the scope of proposed changes and the rules of the destination repository. 拉取请求提交后,可能会遇到以下一种或多种情况:After your pull request is submitted, you can expect one or more of the following to happen:

  • 可合并性:首先进行基准 GitHub 可合并性测试,验证分支中的建议更改是否与目标分支冲突。Mergeability: A baseline GitHub mergeability test occurs first, to verify whether the proposed changes in your branch are not in conflict with the destination branch. 如果拉取请求指示未通过该测试,则必须协调导致合并冲突的内容,然后才能继续进行处理。If the pull request indicates that this test failed, you must reconcile the content that is causing the merge conflict before processing can continue.
  • CLA:如果将内容提交到公共存储库并且你不是 Microsoft 员工,根据建议更改的规模,你可能需要在首次向该存储库提交拉取请求时完成简短的贡献许可协议 (CLA)。CLA: If you are contributing to a public repository and are not a Microsoft employee, depending on the magnitude of the proposed changes, you might be asked to complete a short Contribution License Agreement (CLA) the first time you submit a pull request to that repository. 完成 CLA 步骤后,才会处理拉取请求。After the CLA step is cleared, your pull request is processed.
  • 标记:标签会自动应用于拉取请求,用于指示拉取请求在通过验证工作流程时的状态。Labeling: Labels are automatically applied to your pull request, to indicate the state of your pull request as it passes through the validation workflow. 例如,新的拉取请求可能会自动接收“不合并”标签,指示该拉取请求尚未完成验证、审阅和注销步骤。For instance, new pull requests might automatically receive the "do-not-merge" label, indicating that the pull request has not yet completed the validation, review, and sign-off steps.
  • 验证和生成:自动检查将验证更改是否通过验证测试。Validation and build: Automated checks verify whether your changes pass validation tests. 验证测试可能生成警告或错误,你需要对拉取请求中的一个或多个文件进行更改,然后才能将其合并。The validation tests might yield warnings or errors, requiring you to make changes to one or more files in your pull request before it can be merged. 验证测试结果将以备注的形式添加到拉取请求中供你审阅,可通过电子邮件发送给你。The validation test results are added as a comment in your pull request for your review, and they might be sent to you in e-mail.
  • 过渡:受更改影响的文章页面会自动部署到过渡环境,供验证和生成成功后进行审阅。Staging: The article pages affected by your changes are automatically deployed to a staging environment for review upon successful validation and build. PR 备注中包含预览 URL。Preview URLs appear in a PR comment.
  • 自动合并:拉取请求在通过验证测试并满足某些条件后可能会进行自动合并。Auto-merge: The pull request might be automatically merged, if it passes validation testing and certain criteria. 在这种情况下,不需要执行其他操作。In this case, you don't need to take any further action.

审阅和注销Review and sign-off

所有 PR 处理完成后,应审阅结果(PR 备注、预览 URL 等),在签核合并前决定是否需要对其文件进行其他更改。After all PR processing is completed, you should review the results (PR comments, preview URLs, etc.) to determine if additional changes to its files are required before you sign off for merging. PR 审阅者审阅拉取请求后,如果存在明显的问题需在合并前解决,审阅者还可通过备注提供反馈。If a PR reviewer has reviewed your pull request, they can also provide feedback via comments if there are outstanding issues/questions to be resolved prior to merge.

注释自动化通过向拉取请求分配相应的标签,使读取级别的用户(对存储库没有写入权限的用户)能够执行写入级别的操作。Comment automation enables read-level users (users who don't have write permissions in a repo) to perform a write-level action, by assigning the appropriate label to a pull request. 如果在已实现注释自动化的存储库中操作,请使用下表中列出的井号标签分配标签、更改标签或关闭拉取请求。If you are working in a repository where comment automation has been implemented, use the hashtag comments listed in the following table to assign labels, change labels, or close a pull request. 每当对你的文章提出建议的更改时,Microsoft 员工也会收到电子邮件通知,内容与审阅和签核公共存储库 PR 有关。Microsoft employees will also be notified via e-mail for review and sign-off of public repository PRs, whenever changes are proposed to articles for which you are the author.

井号标签注释Hashtag comment 作用What it does 存储库可用性Repo availability
#sign-off 如果文章作者在注释流中键入 #sign-off 注释,将分配“合并准备就绪”标签 。When the author of an article types the #sign-off comment in the comment stream, the ready-to-merge label is assigned. 通过此标签,存储库中的审阅者可以了解拉取请求可供审阅/合并的时间。This label lets the reviewers in the repo know when a pull request is ready for review/merge.

如果参与者是未被列出的作者,且试图使用 #sign-off 注释对公共拉取请求进行签核,将向拉取请求编写一条消息,指示仅作者可分配该标签。If a contributor who is not the listed author tries to sign off on a public repo pull request by using the #sign-off comment, a message is written to the pull request indicating that only the author can assign the label.
公共和专用Public and private
#hold-off 作者可在 PR 注释中键入 #hold-off,以在改变想法或操作有误时删除“合并准备就绪”标签 。Authors can type #hold-off in a PR comment to remove the ready-to-merge label--in case they change their mind or make a mistake. 在专用存储库中,此操作将分配“请勿合并”标签 。In the private repo, this assigns the do-not-merge label. 公共和专用Public and private
#please-close 如果作者决定不合并更改,可在注释流中键入 #please-close,关闭拉取请求。Authors can type #please-close in the comment stream to close the pull request if they decide not to have the changes merged. 公共Public

拉取请求没有问题并签核后,更改将合并回父分支并关闭拉取请求。When the pull request is issue-free and signed off, your changes are merged back into the parent branch and the pull request is closed.

发布Publishing

请记住,拉取请求必须由 PR 审阅者进行合并,然后更改才能包括在下个计划发布运行中。Remember, your pull request has to be merged by a PR reviewer before the changes can be included in the next scheduled publishing run. 拉取请求通常按提交顺序审阅/合并。Pull requests are normally reviewed/merged in the order of submission. 如果拉取请求需针对特定发布运行进行合并,你需要提前与 PR 审阅者合作,确保在发布前进行合并。If your pull request requires merging for a specific publishing run, you will need to work with your PR reviewer ahead of time to ensure that merging happens prior to publishing.

供稿内容在得到批准并进行合并后,Docs.Microsoft.Com 发布过程会选取这些内容。After your contributions are approved and merged, the docs.microsoft.com publishing process picks them up. 发布时间可能不同,具体取决于管理内容被提交到的存储库的团队。Depending on the team that manages the repository you are contributing to, publishing times can vary. 以下路径下发布的文章通常部署时间约为太平洋时间星期一到星期五上午 10:30 和下午 3:30:Articles published under the following paths are normally deployed at approximately 10:30 AM and 3:30 PM Pacific Time, Monday-Friday:

文章发布后出现在网上最多耗时 45 分钟。It can take up to 45 minutes for articles to appear online after publishing. 文章发布后,可在相应 URL 处验证更改:https://docs.microsoft.com/<path-to-your-article-without-the-md-extension>After your article is published, you can verify your changes at the appropriate URL: https://docs.microsoft.com/<path-to-your-article-without-the-md-extension>.

后续步骤Next steps

就这么简单!That's it! 你已完成参与 docs.microsoft.com 内容的供稿!You've made a contribution to docs.microsoft.com content!

  • 继续查看 Markdown 引用一文,详细了解 Markdown 和 Markdown 扩展语法等主题。To learn more about topics such as Markdown and Markdown extensions syntax, continue to the Markdown reference article.