canonical · cpaelzer · Jul 11, 2023 · May 31, 2023 · May 30, 2023 · May 30, 2023
diff --git a/.github/actions/spelling/allow/misc.txt b/.github/actions/spelling/allow/misc.txt
@@ -25,6 +25,10 @@ testplans
 todo
 todos
 toolchain
+transition
+transitions
+transitioned
+transitioning
 upstream
 upstreamed
 upstreaming

diff --git a/.github/actions/spelling/allow/ubuntu-misc.txt b/.github/actions/spelling/allow/ubuntu-misc.txt
@@ -14,7 +14,9 @@ multiverse
 nbs
 restricted
 sru
+triage
 triaged
+triaging
 uife
 universe
 wontfix
diff --git a/README.md b/README.md
@@ -12,60 +12,90 @@
 
 That is the *Main Inclusion Review* =\> MIR
 
-## Process states
-
-This is supposed to be an overview of MIR bug status (as there was
-enough confusion in the past). Especially to make clear who\'s turn it
-is to act next on a MIR bug.
-
-| State                                   | Explanation |
-| -----                                   | ------- |
-| 1. New/Confirmed (unassigned)           | Bug is new for the MIR team to dispatch it to a MIR Team member |
-| 2. New/Confirmed (assigned)             | on the TODO list of the assigned MIR team member |
-| 3. New/Confirmed (assigned to Security) | on the TODO list of the Security Team |
-| Hint: from #2/#3 to #4/#5/#8 | The successor of these states depends (as seen by multiple potential arrows in the infographic) on the packages current state in the archive. #8 Nack is set to Won\'t Fix and the former reviewer unassigned - if there is context to believe that there might be a follow up by the reporter it might be assigned to them. In case of an Ack it depends on the state of the package - if the package is already tried to be pulled into main (seen in component mismatches) then the next state is #5 (Fix Committed), otherwise the next state is #4 (In Progress) |
-| 4. In Progress (any)                    | MIR team ack (and if needed Security Team ack) done, but now needs the Dependency/Seed change to happen to pull it into Main |
-| 5. Fix Committed (any)                  | All of the above done, waiting for an AA (Archive Admin) to promote the packages |
-| 6. Fix Released (any)                   | Case resolved by an AA |
-| 7. Incomplete (any)                     | Questions/Requests were raised for the bug reporter to resolve/clarify |
-| 8. Won\'t Fix (any)                     | Final Nack or given up by the bug reporter |
-| 9. Invalid (any)                        | No Feedback for a while when in incomplete status |
-
-```
-          Answered       +-7----------+     No feedback        +-9-------+
-      +------------------+ Incomplete +------------------------> Invalid |
-      |   old assign can | any        <--------------------+   | any     |
-      |   be kept as-is  +-----^------+                    |   +---------+
-      |                        |    question               |
-      |                        |                           |
-+-1---v-------+  Triage  +-2---+----+ Security needed  +-3-+------------------+
-|  New/Conf   +--------->+ New/Conf +----------------->+ New/Conf             |
-| unassigned  |          | assigned |                  | assigned to Security |
-+-------------+          +-+--+--+--+                  +-+--+--+--------------+
-                           |  |  |    +-8-----------+    |  |  |
-                           |  |  +----> Won't Fix   <----+  |  |
-                           |  |   Nack| any         | Nack  |  |
-                           |  |       +-------------+       |  |
-                           |  |                             |  |
-                           |  |       +-4-----------+       |  |
-                           |  +-------> In Progress <-------+  |
-                           |    Ack   | any         |  Ack     |
-                           |          +-------------+          |
-                           |             |Change that pulls    |
-                           |             |into Main            |
-+-6------------+           |         +-5-v-----------+         |
-| Fix Released |           +---------> Fix Committed <---------+
-| any          <---------------------+ any           |
-+--------------+  AA promotes        +---------------+
+## Process States
+
+This overview aims to clarify the meaning of MIR bug states, address previous 
+confusion, and indicate the next course of action on a MIR bug.
+
+```mermaid
+%% mermaid flowcharts documentation: https://mermaid.js.org/syntax/flowchart.html
+%%{ init: { 'flowchart': { 'curve': 'monotoneY' } } }%%
+flowchart TD
+    %% Styles
+    classDef Invisible stroke-width:0,fill:#00000000 
+
+    %% States
+    Unassigned["<b><i>1.</i> New / Confirmed¹<br>(unassigned)</b>"]
+    AssignedToMirTeamMember["<b><i>2.</i> New / Confirmed¹<br>(assigned to MIR team member)</b>"]
+    AssignedToSecurityTeamMember["<b><i>3.</i> New / Confirmed¹<br>(assigned to Security team member)</b>"]
+    WontFix[["<b><i>7.</i> Won't Fix</b>"]]
+    InProgress["<b><i>4.</i> In Progress</b>"]
+    FixCommitted["<b><i>5.</i> Fix Committed</b>"]
+    FixReleased[["<b><i>6.</i> Fix Released</b>"]]
+    Incomplete["<b><i>8.</i> Incomplete</b>"]
+    Invalid[["<b><i>9.</i> Invalid</b>"]]
+
+    %% Meta States
+    Start((" ")):::Invisible
+    BugCreated>"Bug created"]
+    IsSecurityReviewNeeded{{"is Security Review needed"}}
+    Reviewed{{"Reviewed<br><i>(report added as bug comment)</i>"}}
+    QuestionsArise>"Questions or Requests arise"]
+
+    %% Transitions
+    Start-->|"create MIR bug<br>following the template"| BugCreated
+    BugCreated-->|"subscribe Launchpad team<br><code>~ubuntu-mir</code> to the bug"|Unassigned
+
+    Unassigned -->|"triaged at MIR team meeting"| AssignedToMirTeamMember
+    AssignedToMirTeamMember --> IsSecurityReviewNeeded -->|"yes"| AssignedToSecurityTeamMember
+
+    IsSecurityReviewNeeded -->|"no"| Reviewed
+    AssignedToSecurityTeamMember --> Reviewed
+    Reviewed -->|"MIR team NACK"| WontFix
+    Reviewed -->|"MIR team ACK"| InProgress
+
+    InProgress -->|"Dependency/Seed change that<br>pulls package(s) into <code>main</code>/<code>restricted</code>"| FixCommitted
+    FixCommitted -->|"Archive Admin (AA)</br>promotes package(s)"| FixReleased
+
+    AssignedToSecurityTeamMember --> QuestionsArise
+    AssignedToMirTeamMember --> QuestionsArise
+    QuestionsArise --> Incomplete
+    Incomplete -->|"Questions or<br>Requests resolved"| Unassigned
+    Incomplete -->|"no response by the bug<br>reporter/driver within 60 days"| Invalid
 ```
 
-Note1: Since many people set things to confirmed once they are sure it
-*exists* all too often bugs get set to confirmed. Since confirmed does
-not have any meaning for our process we will handle new\<-\>confirmed as
-if the\'y be the same.
-
-Note2: All other combinations are undefined and should be fixed up to
-one of the defined states
+| State                                                    | Explanation |
+|----------------------------------------------------------|-------------|
+| *1.* New / Confirmed¹ (unassigned)                       | bug is queued for assignment to a MIR team member |
+| *2.* New / Confirmed¹ (assigned to MIR team member)      | on the TODO list of the assigned MIR team member |
+| *3.* New / Confirmed¹ (assigned to Security team member) | on the TODO list of the Security team member |
+| *4.* In Progress                                         | MIR team ACK (and if needed, Security team ACK) done, but now needs the Dependency/Seed change to happen to pull package(s) into `main`/`restricted` |
+| *5.* Fix Committed                                       | all of the above done; waiting for an Archive Admin to promote the package(s) to `main`/`restricted` |
+| *6.* Fix Released                                        | case resolved by an Archive Admin |
+| *7.* Won\'t Fix                                          | final NACK from MIR team or bug reporter gave up |
+| *8.* Incomplete                                          | Questions/Requests were raised for the bug reporter to resolve/clarify |
+| *9.* Invalid                                             | no response within 60 days when in `Incomplete` state |
+
+**Note:** All other states are undefined and should be resolved to
+one of the defined states – otherwise they might be completely missed on the weekly checks.
+
+**Hint:** transitioning from *2.*/*3.* to *4.*/*5.*/*8.*: The successor of 
+assigned `New` states depends *(as seen by multiple arrows in the state 
+diagram)* on the package(s) current state in the archive: 
+ * A NACK from the MIR or Security team will result in the `7. Won't Fix` state.
+   A former reviewer will get unassigned. (If there is context to believe that 
+   there might be a follow up by the reporter the reviewer might keep assigned.)
+ * In case of an ACK from the MIR team (and, if required the Security team), if 
+   the package(s) is/are already tried to be pulled into `main`/`restricted` 
+   then the next state is `5. (Fix Committed)`, otherwise the next state is 
+   `4. In Progress`. Seen in:
+     * [component mismatches for `main`/`restricted`](https://people.canonical.com/~ubuntu-archive/component-mismatches.svg) 
+     * [component mismatches for `proposed`](https://people.canonical.com/~ubuntu-archive/component-mismatches-proposed.svg)
+
+**¹** Since many people set Launchpad bugs to `Confirmed` once they verified 
+the validity of a problem, MIR bugs often get set to `Confirmed`. Since 
+`Confirmed` does not have any meaning for our process, we will handle `New` and 
+`Confirmed` as if they are the same.
 
 # Exceptions
 
@@ -799,7 +829,7 @@
 RULE: - Is debian/rules a mess? Ideally it uses dh and overrides to make it as
 RULE:   tiny as possible.
 RULE: - If a package shall be promoted it should NOT be on the lto-disabled
 RULE:   list, but the fix, or the workaround should be directly in the package
 RULE:   to enforce maintainer awareness and make it more visible to anyone
 RULE:   looking at the package - see https://wiki.ubuntu.com/ToolChain/LTO.

@@ -819,7 +849,7 @@
 TODO: - no massive Lintian warnings
 TODO: - debian/rules is rather clean
 TODO: - It is not on the lto-disabled list
 RULE:   (fix, or the workaround should be directly in the package,
 RULE:    see https://launchpad.net/ubuntu/+source/lto-disabled-list)

 TODO-A: Problems:
@@ -909,7 +939,7 @@
 #topic MIR related Security Review Queue
 Mission: Check on progress, do deadlines seem doable?

 Some clients can only work with one, some with the other escaping - the URLs point to the same place.
 #link https://bugs.launchpad.net/~ubuntu-security/+bugs?field.searchtext=%5BMIR%5D&assignee_option=choose&field.assignee=ubuntu-security&field.bug_reporter=&field.bug_commenter=&field.subscriber=ubuntu-mir
 #link https://bugs.launchpad.net/~ubuntu-security/+bugs?field.searchtext=[MIR]&assignee_option=choose&field.assignee=ubuntu-security&field.bug_reporter=&field.bug_commenter=&field.subscriber=ubuntu-mir

@@ -932,7 +962,7 @@
 * `check-mir` can be run from a checked out source and tell you which dependencies are in universe.
 * `seeded-in-ubuntu PACKAGE` can tell you whether and how a given PACKAGE is seeded
 * `reverse-depends` can tell you reverse source or binary depends, per component
-* The [component mismatches](https://people.canonical.com/~ubuntu-archive/component-mismatches.svg)
+* The [component mismatches](https://people.canonical.com/~ubuntu-archive/component-mismatches-proposed.svg) and [`proposed` component mismatches](https://people.canonical.com/~ubuntu-archive/component-mismatches.svg)
 
 ## Making Life Easier for Archive Team Members