制作成功的拉取请求#

对 Bokeh 代码库和文档的所有更改都通过拉取请求进行管理。

先决条件#

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

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

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

拉取请求工作流程#

  1. 找到要引用的 issue

    对 Bokeh 仓库的每个拉取请求都始于一个 issue。有关例外情况的更多信息，请参阅 Bokeh wiki 中的拉取请求。

    首先，从 Bokeh 的 issue 跟踪器中选择一个 issue。标记为good first issue 的 issue 相对容易上手。

    接下来，在 issue 的讨论中发布评论，表明您正在处理此 issue。 如果尚无 issue，您应首先创建一个。

  2. 创建分支

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

    使用此模式命名您的分支

    [issue 编号]_[简短描述]

    例如

    11423_table_column_add_visible

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

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

    git checkout -b 11423_table_column_add_visible

  3. 将提交添加到您的本地分支

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

    git status

    当您对当前的更改感到满意时，暂存每个修改后的文件

    git add filename1 filename2 filenameN

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

    git commit -m "描述更改的单行消息"

  4. 将您的本地分支推送到 GitHub 上的 fork

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

    git push --set-upstream origin 11423_table_column_add_visible

  5. 打开新的拉取请求

    在发布您的分支并添加第一个提交后，转到 GitHub 上的 Bokeh 仓库。 GitHub 应该已检测到您最近对分支的更新。在这种情况下，GitHub 将建议为您打开一个拉取请求。如果不是，请切换到顶部菜单中的“拉取请求”选项卡，然后使用“新建拉取请求”按钮。

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

  6. 编写您的拉取请求

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

    首先，为您的拉取请求输入标题。此标题应明确说明您的拉取请求的作用。例如：“修复 PNG 导出”、“向测试添加面板”或“文档 SVG 后端”。

    接下来，输入描述。包括一些关于您的拉取请求的作用以及您为什么决定以这种方式编写的背景信息。此外，链接到您的拉取请求所基于的 issue。为此，请使用诸如“fixes”之类的关键字，后跟 issue 的编号。例如“Fixes #11479”。有关更多信息，请参阅 使用关键字将拉取请求链接到 issue 中的 GitHub 文档。您的描述还应包括关于测试和文档的信息（如果适用）。

  7. 向您的拉取请求添加更多提交

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

  8. 寻找下一个要处理的 issue

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

    一旦您成功完成两个实质性的拉取请求，您就有资格成为Bokeh 开发团队的成员。这意味着您将拥有对 Bokeh 仓库的直接访问权限，而无需使用 fork 等。有关 Bokeh 项目中所有角色的更多信息，请参阅 BEP 4：项目角色。

提示#

如果您有任何疑问或在拉取请求中遇到任何问题，请在 Bokeh 的贡献者 Slack 或 Bokeh Discourse 上联系我们。另外，请查看贡献者可用的其他资源。

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

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

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

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

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

  • 保持讨论集中。当出现新的或相关的主题时，最好创建一个新的 issue，而不是使讨论偏离方向。

  • 不要提交未经宣布的大型拉取请求。相反，提交一个 issue 并开始讨论要采取的方向，然后再投入大量时间。

  • 永远不要提交您没有编写（或没有必要权利）的代码或文档。如果您发现与Bokeh 的 BSD 许可证兼容的代码或文本，并且您认为添加到 Bokeh 会很有用，请提交一个 issue并首先开始讨论。

  • 如果您的拉取请求包含其他或更新的依赖项，则需要在 Bokeh 的环境文件 中的 conda 文件夹中更新它们。

有关标签和拉取请求管理过程的更多信息，请参阅 BEP 1：Issue 和 PR 管理中的“拉取请求”部分。