Join GitHub today
GitHub is home to over 28 million developers working together to host and review code, manage projects, and build software together.Sign up
BEP 1: Issues and PRs management
|BEP 1||Issues and PRs management.|
|Authors||Damián Avila, Bryan Van de Ven|
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.
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: trackerused to track external Bokeh questions or comments from StackOverflow, Twitter, etc.
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
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
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.
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.
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
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: memory- indicates a memory leak or excessive usage; preferably should be accompanied with a profiler report
tag values can be added more liberally, at the discretion of team members, but must have a corresponding issue (
tag: labels) to document the change.
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
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): 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
long-term milestones, the milestone should be updated accordingly.
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
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.zmilestone must be assigned.
Issues in the
short-termmilestone 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-termmilestone can not be assigned.
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
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.