BEP 1: Issues and PRs management

Mateusz Paprocki edited this page Jan 10, 2017 · 56 revisions
BEP 1 Issues and PRs management.
Authors Damián Avila, Bryan Van de Ven
Status Implemented

These are some guidelines to deal with our Issues and Pull Requests (PR's).


Issues are classified by a type label, a reso (resolution) label, zero or more tag labels, and a time which is reflected in an associated milestone.

Issue types

The first classification is type, which is one of five mutually exclusive type values:

  • type: bug: a fix for a bug or unintended behaviour
  • type: feature: a self-contained enhancement
  • type: task: something that needs to be done
  • type: discussion: discussion of general questions, ideas, design, etc.
  • type: tracker used to track external Bokeh questions or comments from StackOverflow, Twitter, etc.

New type values will only be considered after discussion in a new BEP, and must have accompanying documentation updates.

All issues must be tagged with a type as soon as possible, and before they are closed

Issue resolutions

The next classification is reso, which is one of several mutually exclusive resolution status values:

  • reso: invalid: the reported problem cannot be reproduced, or the requested feature or task is not appropriate
  • reso: wontfix: determined to be a real issue, but for strong reasons the behaviour will not be changed
  • reso: upstream: resolution depends on actions of other 3rd projects
  • reso: duplicate: the issue has already been reported. (Link to original issue should be included)
  • reso: completed: successful and complete resolution
  • reso: referred: a general support question was referred to another forum for support

New reso values will only be considered after discussion in a new BEP, and must have accompanying documentation updates.

All issues must be tagged with a resolution when they are closed. If issues are reopened the reso tag should be removed until they are closed again.

Issue priority

All issues are assumed normal priority and don't have to be labeled explicitly. If there is a necessity to bring more attention to an issue, use one of the following:

  • priority: critical: action on an issue must be taken as soon as possible by the assignee. There must be at least one developer assigned to such issue at the time of setting this level of priority.

Issue platform

Another classification is plat. These are optional, NON-mutually exclusive classifiers that can be applied to an issue to note a platform or browser specific dependency. These are the current plat values:

  • plat: windows
  • plat: osx
  • plat: linux
  • plat: firefox
  • plat: chrome
  • plat: ie
  • plat: safari

Issue tags

The last classification is tag. These are optional, NON-mutually exclusive classifiers that can be applied to an issue to provide more query resolution and cross-type grouping. These are the current tag values:

  • tag: BEP
  • tag: bokehjs
  • tag: build
  • tag: charts
  • tag: docs
  • tag: examples
  • tag: labels
  • tag: models
  • tag: py3
  • tag: regression
  • tag: memory - indicates a memory leak or excessive usage; preferably should be accompanied with a profiler report
  • tag: server
  • tag: starter
  • tag: tests

New tag values can be added more liberally, at the discretion of team members, but must have a corresponding issue (type: discussion, tag: labels) to document the change.

Issue times

We use Github milestones to represent a relative time-scale classification for Issues.

These are the current mutually exclusive milestones:

  • x.y.z: collects issues to resolve for the next release.

This milestone is created any time a new version release is planned, and incorporates all the desired Issues from the short-term milestone (see below). It is closed immediately after the release is made. In some situations, usually when you are handling point and major releases concurrently, more than one x.y.z milestones can co-exist.

  • short-term: collects issues that need to be resolved soon, but not before the next release.

This milestone is always open and it gets populated from the either the long-term milestone or from new (unmilestoned) issues.

  • long-term: collects issues that need to be resolved on a medium-to-long time frame.

Such issues may require extensive work, or possibly archictecutual changes. This milestone is always open and is populated from new (unmilestoned) issues.

  • (unmilestoned): Newly created Issues that do not yet have an associated milestone.

All new issues except type: discussion should be assigned to a milestone as soon as possible. The Issues in this group can feed any milestone classification depending according to team members' evaluation.

If you start to work in an Issue from the short-term or long-term milestones, the milestone should be updated accordingly.

Pull Requests

PR's are usually associated/linked with Issues. The natural path is from Issue to PR. But sometimes a new PR is created without an associated Issue. In such cases a new Issue should be created for that PR to engage people in a general discussion, not the technical review which is performed in the PR itself.

When you open a PR and it has an associated Issue, you have to link to it at the top of the PR discussion (first message/post, otherwise it will not automatically close the Issue when the associated PR gets merged) with the next reference: issues: fixes #xxxx, where xxxx is the number of the associated Issue (you can associated more than one issue per PR). PRs do NOT have to be milestoned except in some corner cases (standalone PRs, see next paragraph) because the associated Issue is responsible to carry this information.

If the PR does not need a discussion (trivial fixes, tasks, etc), you can avoid the opening of an associated Issue, but you have to add a type, a reso, a milestone and, optionally, a tag label as with any other common Issue. Also, you have to add this reference issues: none at the top of the first message/post. These Issues/PRs are commonly know as standalone PRs and they have to be exceptions (low frequency situation).

We use mutually exclusive Github labels with the prefix status: to classify PR's.

  • status: WIP: work in progress, exposed for early feedback or discussion. WIP PR's cannot be paused, however, after 1 month (30 days) of inactivity, a WIP PR may be closed for housekeeping.
  • status: ready: ready for review
  • status: accepted: reviewed and accepted for merging
  • status: paused: two weeks (14 days) without any activity. A paused PR will be closed after 1 month (30 days) of further inactivity.
  • status: rejected: reviewed and rejected for merging
  • status: superseded: reviewed and rejected in favour of a different PR for the same Issue

All PR's must be tagged with a status at all times

Github notifies team member when labels are changed, so it is useful to keep the status of each PR as close as possible with the reality, e.g., if you realize that your PR needs more work after a first pass review, then change the label to status: WIP. When the PR is ready for review again, change the label to status: ready and the team will be notified to begin a new round of reviews.



Our form of assignment is soft in that we work collaboratively on the resolution of tasks, bugs, and features. Assignments can change over time, taking into account developer availability, technical skills, and other considerations. But an assignment is a hard commitment to keep an eye on an Issue and help guide it towards a resolution (which may include re-assigning it to others). Issues need a resolution and the assigned developers should be sure to solve the issue themselves or see that is is directed to another team member.

There are some guidelines for assigning Issues with respect to milestones:

  • Issues in the x.y.z milestone must be assigned.

  • Issues in the short-term milestone are not required to be assigned. However, it is good practice to look into this milestone regularly and assign to yourself any Issue that you intend to work on.

  • Issues in the long-term milestone can not be assigned.

Pull Requests

We generally do not assign PR's for review because everyone collaboratively participates in the review of all PR's available at any given time. If a PR submitter would like to have input from particular team members, they should "ping" those individuals by referencing their GitHub username in the discussion, e.g @janedoe.

Additionally, when merging status: accepted PRs, the following plain-label annotations may be added to the PR as appropriate, to help classify and make PRs searchable according to specific criteria:

  • MIGRATION: Changes or updates in this PR should be considered for inclusion in the Migration Guide of the next Release Notes.



Team members can label, assign, or change Issue milestones at any time. We believe in your well-thought analysis of the situation and your choices. In cases of disagreement, this is simply an opportunity to achieve consensus (see below). Everyone is especially encouraged to regard issue labeling as an individual task.


Real time interaction/discussion is the most efficient way to achieve consensus. Accordingly, we have weekly meetings, with recorded minutes, for discussing assignments and milestones or anything that benefits from group discussion.

You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.