Merge pull request #26752 from icecrime/update_triage_process

Update triage process

2 files changed, 29 insertions, 14 deletions

diff --git a/project/ISSUE-TRIAGE.md b/project/ISSUE-TRIAGE.md
index f9dd172860..ac1ea26ba2 100644
--- a/project/ISSUE-TRIAGE.md
+++ b/project/ISSUE-TRIAGE.md
@@ -30,7 +30,12 @@ reopened when the necessary information is provided.
 
 ### 2. Classify the Issue
 
-An issue can have multiple of the following labels.
+An issue can have multiple of the following labels. Typically, a properly classified issues should
+have:
+
+- One label identifying its kind (`kind/*`).
+- One or multiple labels identifying the functional areas of interest (`area/*`).
+- Where applicable, one label categorizing its difficulty (`exp/*`).
 
 #### Issue kind
 
@@ -101,9 +106,8 @@ class="gh-label expert">exp/expert</strong> level task.
 
 ### 3. Prioritizing issue
 
-When attached to a specific milestone, an issue can be attributed one of the
-following labels to indicate their degree of priority (from more urgent to less
-urgent).
+When, and only when, an issue is attached to a specific milestone, the issue can be labeled with the
+following labels to indicate their degree of priority (from more urgent to less urgent).
 
 | Priority    | Description                                                                                                                       |
 |-------------|-----------------------------------------------------------------------------------------------------------------------------------|
diff --git a/project/REVIEWING.md b/project/REVIEWING.md
index f8d9c1dab6..be6c2ba6ae 100644
--- a/project/REVIEWING.md
+++ b/project/REVIEWING.md
@@ -28,16 +28,6 @@ Special status labels:
  * `status/failing-ci`: indicates that the PR in its current state fails the test suite
  * `status/needs-attention`: calls for a collective discussion during a review session
 
-### Specialty group labels
-
-Those labels are used to raise awareness of a particular specialty group, either because we need
-help in reviewing the PR, or because of the potential impact of the PR on their work:
-
- * `group/distribution`
- * `group/networking`
- * `group/security`
- * `group/windows`
-
 ### Impact labels (apply to merged pull requests)
 
  * `impact/api`
@@ -207,3 +197,24 @@ review session. The goal of that session is to agree on one of the following out
  * Escalate to Solomon by formulating a few specific questions on which his answers will allow
    maintainers to decide.
 
+## Milestones
+
+Typically, every merged pull request get shipped naturally with the next release cut from the
+`master` branch (either the next minor or major version, as indicated by the
+[`VERSION`](https://github.com/docker/docker/blob/master/VERSION) file at the root of the
+repository). However, the time-based nature of the release process provides no guarantee that a
+given pull request will get merged in time. In other words, all open pull requests are implicitly
+considered part of the next minor or major release milestone, and this won't be materialized on
+GitHub.
+
+A merged pull request must be attached to the milestone corresponding to the release in which it
+will be shipped: this is both useful for tracking, and to help the release manager with the
+changelog generation.
+
+An open pull request may exceptionally get attached to a milestone to express a particular intent to
+get it merged in time for that release. This may for example be the case for an important feature to
+be included in a minor release, or a critical bugfix to be included in a patch release.
+
+Finally, and as documented by the [`PATCH-RELEASES.md`](PATCH-RELEASES.md) process, the existence of
+a milestone is not a guarantee that a release will happen, as some milestones will be created purely
+for the purpose of bookkeeping