doc/design: clarify the life-cycle of a design doc and update existing accordingly

doc/dev/contribute.rst

@@ -98,6 +98,7 @@ The current members of the TC Implementation are:
 * François Wirz (|span-github| `@FR4NK-W <https://github.com/FR4NK-W>`_, |span-slack| @frank)
 * Lukas Vogel (|span-github| `@lukedirtwalker <https://github.com/lukedirtwalker>`_, |span-slack| @luke)
 * Marc Frei (|span-github| `@marcfrei <https://github.com/marcfrei>`_, |span-slack| @marcfrei)
+* Jordi Subirà (|span-github| `@JordiSubira <https://github.com/JordiSubira>`_, |span-slack| @jordisubira)
 
 
 .. rubric:: Responsibilities and Tasks
@@ -157,7 +158,7 @@ Formal Process
 .. image:: fig/change-proposal-process.excalidraw.png
 
 :Creation: To open a proposal, the author submits a GitHub issue following the
-  proposal template.
+  ``proposal`` template.
 :Review: The proposal may receive feedback from the community, which should be
   incorporated by the author. Moreover, the assigned technical team triages the
   proposal and assigns one of its members to manage the process. The technical
@@ -167,29 +168,46 @@ Formal Process
   The technical team decides to **accept**, **postpone**, or **reject** the
   proposal based on the outcomes of the discussion and feedback from the
   community.
-:Design:
-  If the proposal has been accepted, the authors submit a design document and
-  submit it to the repository (:file-ref:`doc/dev/design`)
-  in the form of a pull request.
-  See :doc:`design/index` for details.
+:Initial Design:
+  If the proposal has been accepted, the authors complete an initial design document
+  and submit it to the repository (:file-ref:`doc/dev/design`)
+  in the form of a pull request. The design document has the status **WIP** and
+  is linked to the WIP section of :doc:`design/index`. Once that pull request is
+  approved and merged, the proposal issue is closed. A new issue (following the ``Work Item``
+  template), owned by the design proponent, is open to track its evolution
+  towards its final form. The title of the issue may be of the form:
+  ``<topic>: finalize design``.
+:Design Improvements:
+  Multiple revisions to the WIP document may be submitted and reviewed as PRs.
+  Participants may discuss any change required via the tracking issue.
 :Final review:
-  The design document will be reviewed by the assigned technical team. Since
-  all major points should already be agreed upon in the proposal review, this
-  final review is expected to be lightweight. After this review, the technical
-  team may start the final comment period, together with a proposition to
-  **merge**, **close**, or **postpone** the proposal.
+  Once the document reaches a form that appears consensual, the technical
+  team starts the final comment period, together with a proposition to
+  **accept**, **postpone**, or **reject** the design.
 
   The **final comment period** lasts **ten calendar days** and is advertised, such that
   stakeholders have a chance to lodge any final objections before a decision is
   reached. If no major comments are raised during the final comment period, the
-  proposed action (close, merge, or postpone) is accepted; otherwise, the
+  proposed action (accept, postpone, reject) is acted; otherwise, the
   proposal goes back to the review step and is discussed further.
+
+  Following the decision, the document's status is changed to one of **Active**, **Postponed**,
+  or **Rejected**, the design document is linked to the corresponding section of the index,
+  and the tracking issue is closed. If the design's new status is **Active**, a new tracking
+  issue is open for its implementation.
 :Implementation:
-  If the final comment period ends with the decision to merge the proposal, it
-  becomes active. The proposal can now be implemented (typically, but not
-  necessarily by the authors). The implementation is submitted as a pull
-  request. The implementation will be reviewed; acceptance of the proposal does
-  not automatically imply that its implementation will be accepted.
+  The design is implemented typically, but not necessarily, by the authors.
+  The implementation is submitted as one or more pull requests. The implementation will be
+  reviewed; acceptance of the design does not automatically imply that its implementation
+  will be accepted.
+
+  Once the implementation is deemed complete, the design document's status is changed to
+  **Complete**, it is linked to the corresponding section of the index, and the
+  implementation tracking issue is closed.
+
+  Should a decision be made to abandon or postpone the implementation, the design document's
+  status is changed to **Postponed**, **Outdated**, or **Rejected**; depending on the reason
+  for the decision.
 
 Learning resources
 ==================

doc/dev/design/BorderRouter.rst

@@ -4,6 +4,7 @@ Border Router Performance Optimized Redesign
 
 - Author: Justin Rohrer
 - Last Updated: 2023-05-25
+- Status: **Completed**
 - Discussion at: `#4334 <https://github.com/scionproto/scion/issues/4334>`_
 
 Abstract

doc/dev/design/EPIC.md

@@ -2,7 +2,7 @@
 
 - Author: Marc Wyss, Markus Legner
 - Last updated: 2020-10-14
-- Status: **implemented**
+- Status: **Completed**
 - Discussion at: [#3884](https://github.com/scionproto/scion/issues/3884)
 - Implemented in: [#3951](https://github.com/scionproto/scion/issues/3951),
                   [#3954](https://github.com/scionproto/scion/issues/3954),

doc/dev/design/NAT-address-discovery.rst

@@ -4,6 +4,7 @@ NAT IP/port discovery
 
 - Author(s): Marc Frei, Tilmann Zäschke
 - Last updated: 2024-07-01
+- Status: **WIP**
 - Discussion at: :issue:`4517`
 
 Abstract

doc/dev/design/PathPolicy.md

@@ -2,7 +2,7 @@
 
 - Authors: Lukas Bischofberger, Lukas Vogel, Martin Sustrik
 - Last updated: 2019-08-30
-- Status: partially **implemented** / partially outdated
+- Status: partially **Completed** / partially **Outdated**
 - Discussion at: [#1909](https://github.com/scionproto/scion/pull/1909),
                  [#1976](https://github.com/scionproto/scion/pull/1976),
                  [#2324](https://github.com/scionproto/scion/pull/2324),

doc/dev/design/TEMPLATE.rst

@@ -5,6 +5,7 @@
 - Author(s): [Author Name(s)]
 - Last updated: [Date (Year-Month-Day)]
 - Discussion at: :issue:`NNNN`
+- Status: [**WIP**, **Active**, **Postponed**, **Rejected**, **Outdated**]
 
 Abstract
 ========

doc/dev/design/endhost-bootstrap.rst

@@ -4,7 +4,7 @@ Automated end host bootstrapping
 
 - Author(s): Andrea Tulimiero, François Wirz
 - Last updated: 2021-03-09
-- Status: **implemented** externally in `netsec-ethz/bootstrapper <https://github.com/netsec-ethz/bootstrapper>`_
+- Status: **Completed** externally in `netsec-ethz/bootstrapper <https://github.com/netsec-ethz/bootstrapper>`_
 - Discussion at: `#3943 <https://github.com/scionproto/scion/pull/3943>`_
 
 Overview

doc/dev/design/grpc.rst

@@ -4,7 +4,7 @@ Teaching gRPC some path-awareness
 
 - Author: Dominik Roos
 - Last updated: 2020-09-02
-- Status: **proposal**
+- Status: **Active**
 - Discussion at: -
 
 Abstract

doc/dev/design/index.rst

@@ -8,11 +8,15 @@ See section :ref:`change-proposal-process` for the overview on the overall
 contribution process.
 
 - **Creation**:
-  Design documents are created from the template :file-ref:`doc/dev/design/TEMPLATE.rst`. While the design is still being discussed, it is linked in the
-  section :ref:`design-docs-wip`
+  Design documents are created from the template :file-ref:`doc/dev/design/TEMPLATE.rst`.
+  While the design is still being discussed, it is in status **WIP** and linked in the
+  section :ref:`design-docs-wip`. The document can be merged in this state as soon as the
+  proposal is accepted, even if it still needs more work.
+
+  Once discussion on the design converges and the design document is finalized, its status
+  becomes one of **Active**, **Postponed**, or **Rejected** and it is inserted to the corresponding
+  section.
 
-  Once discussion on a change proposal converges and a design document is
-  approved, it is inserted to section :ref:`design-docs-active`.
 - **Implementation**:
   Together with the implementation of the change, user manuals and any other
   documentation are updated.
@@ -21,15 +25,19 @@ contribution process.
   found to be necessary during this phase.
 - **Completion and Freeze**:
   Once all parts of the implementation are completed, the design document is
-  marked as complete and the document moves to the section :ref:`design-docs-completed`.
+  marked as **Completed** and linked to section :ref:`design-docs-completed`.
 
   After this point, the design document is frozen as historical record and no
   longer updated. Later substantial changes undergo the entire process again,
   creating new design documents where appropriate.
+
+  During implementation the design may also become suspended (**Postponed**)
+  or abandonned (**Rejected** or **Outdated**).
+
 - **Replacement**:
   If the implementation has changed so much that a design document is no longer
-  a useful reference for the current system, it moves to section :ref:`design-docs-outdated`.
-
+  a useful reference for the current system, it's status is changed to **Outdated**
+  and it is linked to section :ref:`design-docs-outdated`.
 
 .. _design-docs-wip:
 
@@ -40,6 +48,15 @@ WIP
 
    NAT-address-discovery
 
+.. _design-docs-postponed:
+
+Postponed
+=========
+.. toctree::
+   :maxdepth: 1
+
+   scmp-authentication
+
 .. _design-docs-active:
 
 Active
@@ -49,10 +66,8 @@ Active
 
    uri
    grpc
-   BorderRouter
    router-perf-model
    router-port-dispatch
-   scmp-authentication
 
 .. _design-docs-completed:
 
@@ -64,6 +79,7 @@ Completed
    EPIC
    PathPolicy
    endhost-bootstrap
+   BorderRouter
 
 .. _design-docs-outdated:
 
@@ -77,6 +93,12 @@ Outdated
    forwarding-key-rollover
    ColibriService
 
+.. _design-docs-rejected:
+
+Rejected
+========
+.. toctree::
+   :maxdepth: 1
 
 .. seealso::
 

doc/dev/design/router-perf-model.rst

@@ -4,6 +4,7 @@ Router benchmark observations and predictive model
 
 -  Author(s): Jean-Christophe Hugly
 -  Last updated: 2024-04-22
+-  Status: **Active**
 -  Discussion at: :issue:`4408`
 
 TL;DR

doc/dev/design/router-port-dispatch.rst

@@ -4,6 +4,7 @@ End hosts without dispatcher
 - Author: Matthias Frei.
   Originally proposed by Sergiu Costea.
 - Last updated: 2024-03-26
+- Status: **Active**
 - Discussion at: https://github.com/scionproto/scion/issues/3961
 
 Abstract

doc/dev/design/scmp-authentication.rst

@@ -5,11 +5,10 @@ SCMP Authentication
 - Author(s): Matthias Frei
 - Last updated: 2024-05-23
 - Discussion at: :issue:`3969`
-- Status:
-
-  - On hold. No clear consensus that this is the right approach. See "Discussion" section.
-  - Experimental support in router, added in :issue:`4255`.
+- Status: **Postponed**
 
+Reason for postponment: no clear consensus that this is the right approach. See "Discussion" section.
+Experimental support in router, added in :issue:`4255`.
 
 Abstract
 ========

doc/dev/design/uri.rst

@@ -4,7 +4,7 @@ SCION Address URI encoding
 
 - Author: Dominik Roos
 - Last updated: 2020-09-02
-- Status: **proposal**
+- Status: **Active**
 - Discussion at: -
 
 Abstract