BEP 1: Issues and PRs management
| BEP 1 | Issues and PRs management. |
|---|---|
| Authors | Damián Avila, Bryan Van de Ven |
| Status | Implemented |
| Discussion | https://github.com/bokeh/bokeh/issues/973 |
These are some guidelines to deal with our Issues and Pull Requests (PR's).
Issues are classified by having a type label and a reso (resolution) label. Issue may also optionally have any number of tag labels. Issues that are resolved as reso: completed will have a milestone associated.
The first classification is type, which is one of five mutually exclusive type values:
-
type: bug: a fix for a confirmed bug or unintended behavior -
type: feature: a self-contained enhancement or new feature -
type: task: something that needs to be done that is not a bug or feature -
type: discussion: discussion of general questions, ideas, design, etc.
New type values will only be considered after discussion in an issues, 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: completed: successful and complete bugfix, feature, or task. -
reso: duplicate: the issue has already been reported. (Link to original issue should be included) -
reso: invalid: the reported problem cannot be reproduced, or the requested feature or task is not appropriate -
reso: noaction: a suggested feature or task that has been decided not to pursue -
reso: norepro: a reported problem that cannot be reproduced (can be re-ropened with new information) -
reso: referred: a general support question was referred to another forum for support -
reso: upstream: resolution depends on actions of other 3rd party projects -
reso: wontfix: determined to be a real issue, but for strong reasons the behavior will not be changed
New reso values will only be considered after discussion in an issue, 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:
-
CRITICAL: action on an issue must be taken before the next release (or may require a patch release).
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: chromeplat: firefoxplat: ieplat: linuxplat: mobileplat: osxplat: safariplat: windows
Issues may be labeled with informative tags. These are optional, NON-mutually exclusive classifiers that can be applied to an issue to provide more query resolution and cross-type grouping. Some examples of tag values are:
tag: BEPtag: API: modelstag: API: plottingtag: component: bokehjstag: component: docstag: component: testtag: regressiontag: server
The full list of current tag can be viewed here.
New tag values can be added more liberally, at the discretion of team members. When changes to tags are made, a note should be left in the Perpetual BEP-1 Tag Discussion to document the change.
A few special labels exist to denote special specific situations:
-
GOOD FIRST ISSUE: This issues represents self-contained work that would make a good introduction to project development for a new contributor. -
NEEDS MORE INFO: The issue does not contain enough information to evaluate or act. Issues with this label applied may be closed after one week if additional information is not supplied (but may be re-opened later in case it is provided at a later date).
We use Github milestones to proactively describe expected time-scales for Issues.
-
x.yorx.y.z: collects issues to resolve in the next release. It is closed immediately after the release is made. -
(unmilestoned): Newly created Issues that do not yet have an associated milestone or are otherwise unplanned
If you start to work in an Issue, the milestone should be updated to reflect the expected release accordingly.
Full details about the process for milestones is described in BEP 6: Branching Strategy.
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 associate more than one issue per PR).
If the PR does not need a discussion (trivial fixes, tasks, etc), the opening of an associated Issue may be skipped, but the Pull Request must be labeled with all usual Issue labels: a type, a reso, a milestone and, optionally, a tag labels. These are called Issue PRs.
We use mutually exclusive Github labels with the prefix status: to classify PR's.
-
status: accepted: reviewed and accepted for merging -
status: declined: reviewed and rejected for merging -
status: paused: two weeks or more without any activity. A paused PR may be closed after 1 month of further inactivity. -
status: ready: ready for review -
status: superseded: reviewed and rejected in favor of a different PR for the same Issue -
status: WIP: work in progress, exposed for early feedback or discussion. WIP PR's cannot be paused, however, after 30 days of inactivity, a WIP PR may be closed for housekeeping.
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.
We use Github milestones to retroactively describe when work actually was performed in Pull Requests.
At time of release, all Pull Requests that were merged and will be included in the release should be associated with the milestone for that release.
As a volunteer Open-Source project, we do make typically use assignments on issues, other than self-assignments. A self-assignment is a 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.
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. -
PROTOCOL: Changes or updates in this PR should involve the Bokeh wire protocol
Bokeh is a volunteer Open Source project. Individual Dev Team members are largely self-directed according to their own discretion. Developers can label, self-assign, or change Issue milestones at any time. We believe in team member's well-thought analysis of the situation and choices. In cases of disagreement, this is simply an opportunity to achieve group 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 current or upcoming work, milestones and releases, or anything that benefits from group discussion. Formal decision making is described in BEP 7: Decision Making.
Changes to this document shall be recorded below:
| Date | Change |
|---|---|
| 2020-07-11 | Update to reflect current practices |
| 2021-07-07 | Update for tags discussion |