创建一个成功的拉取请求

对Bokeh代码库和文档的所有更改都是通过 pull requests来管理的。

先决条件

创建拉取请求需要一些基本的GitHub知识。有关GitHub和拉取请求的一般信息，请参阅GitHub文档。

要创建拉取请求，您需要一个开发环境，如设置开发环境中所述。

您可以在处理拉取请求时格式化您输入的任何文本。要了解更多关于格式化选项的信息，请参阅在GitHub上写作中的GitHub文档。

拉取请求工作流程

1. Find an issue to reference

   每个对Bokeh仓库的拉取请求都始于一个问题。有关例外的更多信息，请参见Bokeh维基中的拉取请求。

   首先，从Bokeh的问题跟踪器中选择一个问题。相对容易上手的问题被标记为好的第一个问题。

   接下来，在问题的讨论中发布一条评论，表明你正在处理这个问题。如果还没有问题，你应该首先创建一个。

2. Create a branch

   在编写任何代码之前，您需要在Bokeh仓库的您的分支上创建一个新的分支。 在大多数情况下，您应该基于Bokeh的default分支创建新分支。默认分支通常代表Bokeh的下一个版本，例如branch-3.0。

   使用此模式来命名您的分支：

   [issue number]_[short_description]

   例如：

   11423_table_column_add_visible

   有关Bokeh仓库中不同分支的更多信息，请参见BEP 6: 分支策略。

   要创建此示例分支并检出它：

   git checkout -b 11423_table_column_add_visible

3. Add commits to your local branch

   对代码进行一些更改并保存修改后的文件。要查看哪些文件被修改了：

   git status

   当您对当前更改满意时，暂存每个修改过的文件：

   git add filename1 filename2 filenameN

   然后使用提交消息提交更改：

   git commit -m "one-liner describing change"

4. Push your local branch to your fork on GitHub

   在您能够打开一个拉取请求之前，您首先需要将您的分支从本地克隆推送到GitHub上的您的分支。例如：

   git push --set-upstream origin 11423_table_column_add_visible

5. Open a new pull request

   在发布您的分支并添加第一个提交后，前往GitHub上的 Bokeh仓库。GitHub应该已经检测到您对分支的最新更新。在这种情况下，GitHub会建议您打开一个拉取请求。如果没有，请切换到顶部菜单中的“拉取请求”标签，并使用“新建拉取请求”按钮。

   要创建拉取请求，请确保选择您在创建分支时使用的默认分支作为base（例如，branch-3.0）。选择您的分支作为compare。

6. Write your pull request

   创建拉取请求后，GitHub 会将您的分支与基础分支进行比较，并突出显示您提出的所有更改。

   首先，为您的拉取请求输入一个标题。这个标题应该清楚地说明您的拉取请求做了什么。例如：“修复PNG导出”，“添加面板到测试”，或“记录SVG后端”。

   接下来，输入描述。包括一些关于你的拉取请求的背景信息，以及你为什么决定以这种方式编写内容。同时，链接到你的拉取请求所基于的问题。为此，使用一个关键字，如“fixes”后跟问题的编号。例如“Fixes #11479”。有关更多信息，请参阅使用关键字将拉取请求链接到问题在GitHub文档中。你的描述还应包括有关测试和文档的信息，如果适用的话。

7. Add more commits to your pull request

   一旦你创建了一个拉取请求，Bokeh核心团队的成员将开始审查你的拉取请求，并可能请求更改或添加。如果是这样，他们将在你可能有任何问题时帮助你。你可以在现有的本地分支中进行新的更改并将其推送到Github。PR将自动更新，无需打开新的PR。团队成员还将更新你拉取请求中的任何标签。审查拉取请求可能很耗时，所以请注意，可能需要一段时间才能收到反馈。

8. Look for the next issue to work on

   在您的第一个拉取请求合并后，您应该再次查看Bokeh的 问题跟踪器，以找到下一个要处理的问题。

   一旦你成功完成两个实质性的拉取请求，你就有资格成为Bokeh开发团队的成员。这意味着你将直接访问Bokeh仓库，而不需要使用分叉，例如。有关Bokeh项目中所有角色的更多信息，请参见BEP 4: 项目角色。

提示

如果您有任何问题或在提交拉取请求时遇到任何问题， 请在Bokeh的贡献者Slack或Bokeh Discourse上联系我们。 同时，查看贡献者可用的额外资源。

处理拉取请求时需要记住的事项：

• 编写代码时，尽量与现有的编码风格保持一致。

• 尝试将你的工作分成更小的部分，并推送小的、增量的提交。

• 在添加新功能时，包括新测试。

• 在修复错误时，包含tests以检查回归。

• 保持讨论的焦点。当出现新的或相关的话题时，通常最好创建一个新的问题，而不是偏离讨论的主题。

• 不要未经通知就提交一个大的拉取请求。相反，应该先提交一个问题，并在投入大量时间之前开始讨论应该采取什么方向。

• 永远不要提交你未编写（或不具备必要权限）的代码或文档。如果你发现与Bokeh的BSD许可证兼容的代码或文本，并且你认为将其添加到Bokeh中会很有用，请先提交一个问题并开始讨论。

• 如果你的拉取请求包含额外或更新的依赖项，你需要在conda文件夹中更新Bokeh的环境文件。

请参阅BEP 1: 问题和PR管理中的“拉取请求”部分以获取有关标签和拉取请求管理流程的更多信息。