From 0ae79c3c4ef18f6f22e9d0bf384144902d30f6bb Mon Sep 17 00:00:00 2001 From: Anthony Johnson Date: Thu, 31 May 2018 18:05:23 -0600 Subject: [PATCH 1/4] Updates to our triage guidelines A few things I've wanted as I do PM, plus some changes for later automation via probot: * Drop `Enhancement` -- it vaguely implies "new feature" * Instead use `Feature` for new **accepted** and on our roadmap features * If an issue doesn't describe a bug, and is not a new feature, it's likely an Improvement. The distinction here is `Feature` is a new feature, `Bug` has higher priority than `Improvement` * `Needed: more information` is a way to track issues that require a reply and can be closed if we don't get that reply. Currently, we use this in some places as a way to describe issues that we need to collect more ideas on -- a good substitute is `Needed: design decision` * Also add `Status: stale` for issue automation * Drop unused statuses for closed issues * Drop PR: ready as this is a leftover from before GH had reviews * Drop `Feaure Overview`, this is synonymous with `Feature` The takeaway here for purposes of what to audit with these changes in place: * If an issue is an `Enhancement` now: * It becomes a `Feature` if it is a new feature and belongs on our roadmap * It becomes an `Improvement` if it is not a bug and belongs on our roadmap * It gets closed otherwise, it's not important to us * Issues that are `Needed: more information` can be closed if there was no reply after 7 days. We might need to retriage some issues where this label was applied for another reason Also, suggestions for alternatives to `Improvement` are helpful, if this isn't descriptive enough. --- docs/issue-labels.rst | 78 ++++++++++++++++++++----------------------- 1 file changed, 37 insertions(+), 41 deletions(-) diff --git a/docs/issue-labels.rst b/docs/issue-labels.rst index e460439bd1b..fe0afe85586 100644 --- a/docs/issue-labels.rst +++ b/docs/issue-labels.rst @@ -7,41 +7,45 @@ what they stand for. .. _GitHub issue tracker: https://github.com/rtfd/readthedocs.org/issues *Bug* - An issue describing unexpected or malicious behaviour of the - readthedocs.org software. + An issue describing unexpected or malicious behaviour of the readthedocs.org + software. A Bug issue differs from an Improvement issue in that Bug issues + are given priority on our roadmap. On release, these issues generally only + warrant incrementing the patch level version. *Community Effort* - Tickets with this label are valid issues that the core team thinks are + Issues with this label are valid issues that the core team thinks are worth to fix or implement in the future. However the core team's resources - are too scarce to address these issues. Tickets marked with this label + are too scarce to address these issues. Issues marked with this label are issues that the core team will **not** work on, but contributions from the community are very welcome. *Design* Issues related to the UI of the readthedocs.org website. -*Enhancement* - Feature requests and ideas about how to make readthedocs.org better in - general will have this label. - -*Feature Overview* - Features that are too big to be tackled in one ticket are split up into - multiple tickets. A feature overview ticket is then explaining the overarching - idea. See the milestone of the feature overview ticket for all related - tickets. +*Feature* + Issues that describe new features will be given this label **only** once the + feature is an accepted feature on our roadmap. This label does not describe + issues that may become features some day. Issues that do not describe + new features, such as code cleanup or fixes that are not related to a bug, + should probably be given the Improvement label instead. On release, issues + with the Feature label warrant at least a minor version increase. *Good First Issue* - This label marks tickets that are easy to get started with. The ticket + This label marks issues that are easy to get started with. The issue should be ideal for beginners to dive into the code base. *High Priority* - Tickets with this label should be resolved as quickly as possible. + Issues with this label should be resolved as quickly as possible. -*Mkdocs* - Tickets that are related to the Mkdocs builder. +*Improvement* + An issue with this label is not a Bug nor a Feature. Code cleanup or small + changes to existing features would likely have this label. The distinction + for this label is that these issues have a lower priority on our roadmap + compared to issues labeled Bug, and aren't implementing new features, such + as a Feature issue might. *Needed: design decision* - Tickets that need a design decision are blocked for development until a + Issues that need a design decision are blocked for development until a project leader clarifies the way in which the issue should be approached. *Needed: documentation* @@ -49,51 +53,43 @@ what they stand for. assigned. *Needed: more information* - This label indicates that the issue has not enough information in order to - decide on how to go forward. See the documentation about our :ref:`triage - process ` for more information. + This label indicates that a reply with more information is required from the + bug reporter. If no response is given by the reporter, the issue is + considered invalid after 7 days and will be closed. See the documentation + about our :ref:`triage process ` for more + information. *Needed: patch* This label indicates that a patch is required in order to resolve the - ticket. A fix should be proposed via a pull request on GitHub. + issue. A fix should be proposed via a pull request on GitHub. *Needed: tests* This label indicates that a better test coverage is required to resolve - the ticket. New tests should be proposed via a pull request on GitHub. + the issue. New tests should be proposed via a pull request on GitHub. *Needed: replication* This label indicates that a bug has been reported, but has not been successfully replicated by another user or contributor yet. *Operations* - Tickets that require changes in the server infrastructure. - -*PR: ready for review* - Pull Requests that are considered complete. A review by at least one core - developer is required prior to merging it. + Issues that require changes in the server infrastructure. *PR: work in progress* Pull Requests that are not complete yet. A final review is not possible yet, but every Pull Request is open for discussion. *Sprintable* - Sprintable are all tickets that have the right amount of scope to be + Sprintable are all issues that have the right amount of scope to be handled during a sprint. They are very focused and encapsulated. *Status: blocked* - The ticket cannot be resolved until some other ticket has been closed. - See the ticket's log for which ticket is blocking this ticket. - -*Status: duplicate* - See the ticket's log to find the original ticket that this one is a - duplicate of. - -*Status: invalid* - A ticket is invalid if the reported issue cannot be reproduced. + The issue cannot be resolved until some other issue has been closed. + See the issue's log for which issue is blocking this issue. -*Status: rejected* - A ticket gets rejected if the proposed enhancement is not in line with the - overall goals of readthedocs.org. +*Status: stale* + A issue is stale if it there has been no activity on it for 90 days. Once a + issue is determined to be stale, it will be closed in 7 days unless there + is activity on the issue. *Support* Questions that needs answering but do not require code changes or issues From d98189254c383c3f8de17ed0768581c8877df35f Mon Sep 17 00:00:00 2001 From: Anthony Johnson Date: Fri, 8 Jun 2018 10:37:43 -0600 Subject: [PATCH 2/4] 7d -> 2w, drop Community Effort, add Accepted label --- docs/issue-labels.rst | 34 ++++++++++++++++++---------------- 1 file changed, 18 insertions(+), 16 deletions(-) diff --git a/docs/issue-labels.rst b/docs/issue-labels.rst index fe0afe85586..5e82c42986d 100644 --- a/docs/issue-labels.rst +++ b/docs/issue-labels.rst @@ -6,29 +6,31 @@ what they stand for. .. _GitHub issue tracker: https://github.com/rtfd/readthedocs.org/issues +*Accepted* + Issues with this label are issues that the core team has accepted on to the + roadmap. The core team focuses on accepted bugs, features, and improvements + that are on our immediate roadmap and will give priority to these issues. + Pull requests could be delayed or closed if the pull request doesn't align + with our current roadmap. An issue or pull request that has not been + accepted should either eventually move to an accepted state, or should be + closed. As an issue is accepted, we will find room for it on our roadmap, + either on an upcoming release (point release milestones), or on a future + milestone project (named milestones). + *Bug* An issue describing unexpected or malicious behaviour of the readthedocs.org software. A Bug issue differs from an Improvement issue in that Bug issues are given priority on our roadmap. On release, these issues generally only warrant incrementing the patch level version. -*Community Effort* - Issues with this label are valid issues that the core team thinks are - worth to fix or implement in the future. However the core team's resources - are too scarce to address these issues. Issues marked with this label - are issues that the core team will **not** work on, but contributions - from the community are very welcome. - *Design* Issues related to the UI of the readthedocs.org website. *Feature* - Issues that describe new features will be given this label **only** once the - feature is an accepted feature on our roadmap. This label does not describe - issues that may become features some day. Issues that do not describe - new features, such as code cleanup or fixes that are not related to a bug, - should probably be given the Improvement label instead. On release, issues - with the Feature label warrant at least a minor version increase. + Issues that describe new features. Issues that do not describe new features, + such as code cleanup or fixes that are not related to a bug, should probably + be given the Improvement label instead. On release, issues with the Feature + label warrant at least a minor version increase. *Good First Issue* This label marks issues that are easy to get started with. The issue @@ -55,7 +57,7 @@ what they stand for. *Needed: more information* This label indicates that a reply with more information is required from the bug reporter. If no response is given by the reporter, the issue is - considered invalid after 7 days and will be closed. See the documentation + considered invalid after 2 weeks and will be closed. See the documentation about our :ref:`triage process ` for more information. @@ -88,8 +90,8 @@ what they stand for. *Status: stale* A issue is stale if it there has been no activity on it for 90 days. Once a - issue is determined to be stale, it will be closed in 7 days unless there - is activity on the issue. + issue is determined to be stale, it will be closed after 2 weeks unless + there is activity on the issue. *Support* Questions that needs answering but do not require code changes or issues From 595440e64efc1820f296f1daab20f45c26d0fd8f Mon Sep 17 00:00:00 2001 From: Anthony Johnson Date: Fri, 8 Jun 2018 11:25:46 -0600 Subject: [PATCH 3/4] Also make Priority: high and Priority: low Priority: high already exists in rtfd/readthedocs.org. Matching low priority for extra use as well. --- docs/issue-labels.rst | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/docs/issue-labels.rst b/docs/issue-labels.rst index 5e82c42986d..369ea354467 100644 --- a/docs/issue-labels.rst +++ b/docs/issue-labels.rst @@ -36,9 +36,12 @@ what they stand for. This label marks issues that are easy to get started with. The issue should be ideal for beginners to dive into the code base. -*High Priority* +*Priority: high* Issues with this label should be resolved as quickly as possible. +*Priority: low* + Issues with this label won't have the immediate focus of the core team. + *Improvement* An issue with this label is not a Bug nor a Feature. Code cleanup or small changes to existing features would likely have this label. The distinction From 01026829d1425567052b9df83d4c0e1fbd3aa2cd Mon Sep 17 00:00:00 2001 From: Anthony Johnson Date: Fri, 8 Jun 2018 11:35:37 -0600 Subject: [PATCH 4/4] Add PR hotfix --- docs/issue-labels.rst | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/issue-labels.rst b/docs/issue-labels.rst index 369ea354467..28a9f627471 100644 --- a/docs/issue-labels.rst +++ b/docs/issue-labels.rst @@ -83,6 +83,10 @@ what they stand for. Pull Requests that are not complete yet. A final review is not possible yet, but every Pull Request is open for discussion. +*PR: hotfix* + Pull request was applied directly to production after a release. These pull + requests still need review to be merged into the next release. + *Sprintable* Sprintable are all issues that have the right amount of scope to be handled during a sprint. They are very focused and encapsulated.