成功创建 Pull Request#

Bokeh 代码库和文档的所有更改都通过 Pull Request 进行管理。

先决条件#

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

要创建 Pull Request，您需要一个开发环境，如 设置开发环境 中所述。

在使用 Pull Request 时，您可以格式化输入的任何文本。要了解有关格式选项的更多信息，请参阅 GitHub 上的写作，该内容位于 GitHub 文档 中。

Pull Request 工作流程#

  1. 查找要引用的问题

    对 Bokeh 代码库的每个 Pull Request 都从一个问题开始。有关例外情况的更多信息，请参阅 Bokeh Wiki 中的 Pull Request。

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

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

  2. 创建分支

    在编写任何代码之前，您需要在 Bokeh 代码库的 您的 fork 上创建一个新的 分支。在大多数情况下，您应该将新分支基于 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. 将提交添加到您的本地分支

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

    git status

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

    git add filename1 filename2 filenameN

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

    git commit -m "one-liner describing change"

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

    在打开 Pull Request 之前，您首先需要 将您的分支推送到 GitHub 上的您的 fork。例如

    git push --set-upstream origin 11423_table_column_add_visible

  5. 打开新的 Pull Request

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

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

  6. 编写您的 Pull Request

    创建 Pull Request 后，GitHub 将比较您的分支与基准分支，并突出显示您提议的所有更改。

    首先，为您的 Pull Request 输入标题。此标题应清楚地说明您的 Pull Request 的作用。例如：“修复 PNG 导出”、“将面板添加到测试”或“记录 SVG 后端”。

    接下来，输入描述。包含一些关于您的 Pull Request 的作用以及您为何决定以这种方式编写内容的背景信息。此外，链接到您的 Pull Request 所基于的问题。为此，请使用“修复”等关键词，后跟问题的编号。例如“修复 #11479”。有关更多信息，请参阅 在 GitHub 文档中使用关键词将 Pull Request 链接到问题。如果适用，您的描述还应包含有关 测试 和 文档 的信息。

  7. 向您的 Pull Request 添加更多提交

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

  8. 寻找下一个要处理的问题

    合并您的第一个 Pull Request 后，您应该再次查看 Bokeh 的 问题跟踪器 以查找下一个要处理的问题。

    成功完成两个实质性 Pull Request 后，您有资格成为 Bokeh 开发团队 的成员。这意味着您将直接访问 Bokeh 代码库，无需使用 fork 等。有关 Bokeh 项目中所有角色的更多信息，请参阅 BEP 4：项目角色。

提示#

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

在处理 Pull Request 时需要注意的事项

  • 编写代码时，请尝试匹配现有的编码风格。

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

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

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

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

  • 不要未经宣布就提交大型 Pull Request。相反，请先提交问题并开始讨论要采取的方向，然后再投入大量时间。

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

  • 如果您的 Pull Request 包括其他或更新的依赖项，则需要更新 Bokeh 的环境文件（位于 conda 文件夹中）。

有关标签和 Pull Request 管理流程的更多信息，请参阅 “BEP 1：问题和 PR 管理中的 Pull Request”部分。