Making a successful pull request

All changes to Bokeh’s codebase and documentation are managed through pull requests.

Prerequisites

Creating a pull request requires some basic knowledge of GitHub. See the GitHub documentation for general information about GitHub and pull requests.

To create a pull request, you need a development environment as described in Setting up a development environment.

You can format any text you enter when working with pull requests. To learn more about your formatting options, see Writing on GitHub in the GitHub documentation.

Pull request workflow

1. Find an issue to reference

   Every pull request to the Bokeh repository begins with an issue. See Pull Requests in the Bokeh wiki for more information on exceptions.

   First, pick an issue from Bokeh’s issue tracker. Issues that are relatively easy to get started on are labeled good first issue.

   Next, post a comment in the issue’s discussion to indicate that you are working on this issue. If there is no issue yet, you should first create one.

2. Create a branch

   Before writing any code, you need to create a new branch on your fork of the Bokeh repository. In most cases, you should base your new branch on Bokeh’s default branch. The default branch is usually a branch that represents the next version of Bokeh, for example branch-2.4.

   Use this pattern to name your branch:

   [issue number]_[short_description]

   For example:

   11423_table_column_add_visible

   See BEP 6: Branching Strategy for more information on the different branches in the Bokeh repository.

3. Push your local branch to your fork on GitHub

   Before you can open a pull request, you first need to push your branch from your local clone to your fork on GitHub. At this time, you should also include a first commit.

4. Open a new pull request

   After publishing your branch and adding a first commit, go to the Bokeh repository on GitHub. GitHub should have detected your recent updates to your branch. In this case, GitHub will suggest opening a pull request for you. If not, switch to the tab “Pull request” in the top menu and use the button “New pull request”.

   To create a pull request, make sure to select the default branch you used when creating your branch as base (for example, branch-2.4). Select your branch as compare.

5. Write your pull request

   After creating your pull request, GitHub will compare your branch to the base branch and highlight all your proposed changes.

   First, enter a title for your pull request. This title should make clear what your pull request does. For example: “Fix PNG export”, “Add panel to tests”, or “Document SVG backend”.

   Next, enter a description. Include some background about what your pull request does and why you decided to write things the way you did. Also, link to the issue your pull request is based on. To do so, use a keyword such as “fixes,” followed by the number of the issue. For example “Fixes #11479”. See Linking a pull request to an issue using a keyword in the GitHub documentation for more information. Your description should also include information about tests and documentation, if applicable.

6. Add more commits to your pull request

   Once you have created a pull request, a member of the Bokeh core team will begin reviewing your pull request and may request changes or additions. If so, they will help you along the way with any questions you may have. You can make new changes in your existing local branch and push them to Github. The PR will update automatically, there is no need to open a new PR. The team member will also update any labels in your pull request. Reviewing pull requests can be time-consuming, so be aware that it might take a while to receive feedback.

7. Look for the next issue to work on

   With your first pull request merged, you should take another look at Bokeh’s issue tracker to find the next issue to work on.

   Once your successfully complete two substantive pull requests, you are eligible to become a member of the Bokeh development team. This means you will have direct access to the Bokeh repository and won’t need to use a fork, for example. See BEP 4: Project Roles for more information about all roles in the Bokeh project.

Tips

If you have any questions or encounter any problems with your pull request, please reach out on the Bokeh’s contributor Slack or the Bokeh Discourse. Also, check the additional resources available to contributors.

Things to keep in mind when working on a pull request:

• When writing code, try to match the existing coding style.

• Try to divide your work into smaller chunks and push small, incremental commits.

• Include new tests when adding new features.

• Include tests to check for regressions when fixing bugs.

• Keep the discussions focused. When a new or related topic comes up, it’s often better to create a new issue than to sidetrack the discussion.

• Don’t submit a big pull request unannounced. Instead, file an issue and start a discussion about what direction to take before investing a large amount of time.

• Never commit code or documentation that you didn’t write (or don’t have the necessary rights to). If you find code or text that is compatible with Bokeh’s BSD license and that you think would be useful to add to Bokeh, file an issue and start a discussion first.

• In case your pull request includes additional or updated dependencies, you not only need to update environment.yml but also the environment files Bokeh’s CI in the ci folder.

See the “Pull Requests” section in BEP 1: Issues and PRs management for more information about labels and the pull request management process.

Creating issues Writing documentation