From 2711d7167d6c31eacb867aa0446b02a0291d03dc Mon Sep 17 00:00:00 2001 From: Jean-Christophe Hugly Date: Mon, 30 Sep 2024 12:22:58 +0200 Subject: [PATCH 1/4] Clarify the life-cycle of a design doc and update existing accordingly. --- doc/dev/contribute.rst | 52 ++++++++++++++++-------- doc/dev/design/BorderRouter.rst | 1 + doc/dev/design/EPIC.md | 2 +- doc/dev/design/NAT-address-discovery.rst | 1 + doc/dev/design/PathPolicy.md | 2 +- doc/dev/design/TEMPLATE.rst | 1 + doc/dev/design/endhost-bootstrap.rst | 2 +- doc/dev/design/grpc.rst | 2 +- doc/dev/design/index.rst | 40 ++++++++++++++---- doc/dev/design/router-perf-model.rst | 1 + doc/dev/design/router-port-dispatch.rst | 1 + doc/dev/design/scmp-authentication.rst | 7 ++-- doc/dev/design/uri.rst | 2 +- 13 files changed, 79 insertions(+), 35 deletions(-) diff --git a/doc/dev/contribute.rst b/doc/dev/contribute.rst index 2d035f69b8..fb046e9ead 100644 --- a/doc/dev/contribute.rst +++ b/doc/dev/contribute.rst @@ -98,6 +98,7 @@ The current members of the TC Implementation are: * François Wirz (|span-github| `@FR4NK-W `_, |span-slack| @frank) * Lukas Vogel (|span-github| `@lukedirtwalker `_, |span-slack| @luke) * Marc Frei (|span-github| `@marcfrei `_, |span-slack| @marcfrei) +* Jordi Subirà (|span-github| `@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: + `: 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 ================== diff --git a/doc/dev/design/BorderRouter.rst b/doc/dev/design/BorderRouter.rst index 80e54f4117..03f0b01cce 100644 --- a/doc/dev/design/BorderRouter.rst +++ b/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 `_ Abstract diff --git a/doc/dev/design/EPIC.md b/doc/dev/design/EPIC.md index ae54d988a2..bdd0d22ab2 100644 --- a/doc/dev/design/EPIC.md +++ b/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), diff --git a/doc/dev/design/NAT-address-discovery.rst b/doc/dev/design/NAT-address-discovery.rst index ecf50f37cb..802e3f7076 100644 --- a/doc/dev/design/NAT-address-discovery.rst +++ b/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 diff --git a/doc/dev/design/PathPolicy.md b/doc/dev/design/PathPolicy.md index 1d8fa91002..6d76eb6893 100644 --- a/doc/dev/design/PathPolicy.md +++ b/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), diff --git a/doc/dev/design/TEMPLATE.rst b/doc/dev/design/TEMPLATE.rst index d5771cfd17..fbe94166d2 100644 --- a/doc/dev/design/TEMPLATE.rst +++ b/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 ======== diff --git a/doc/dev/design/endhost-bootstrap.rst b/doc/dev/design/endhost-bootstrap.rst index cd040f0c6c..0b80a4a6c3 100644 --- a/doc/dev/design/endhost-bootstrap.rst +++ b/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 `_ +- Status: **Completed** externally in `netsec-ethz/bootstrapper `_ - Discussion at: `#3943 `_ Overview diff --git a/doc/dev/design/grpc.rst b/doc/dev/design/grpc.rst index 8e8aab67c8..066d98ecfd 100644 --- a/doc/dev/design/grpc.rst +++ b/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 diff --git a/doc/dev/design/index.rst b/doc/dev/design/index.rst index b5c02a7a42..b6686ae71f 100644 --- a/doc/dev/design/index.rst +++ b/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,7 +93,13 @@ Outdated forwarding-key-rollover ColibriService +.. _design-docs-rejected: +Rejected +======== +.. toctree:: + :maxdepth: 1 + .. seealso:: :ref:`change-proposal-process` diff --git a/doc/dev/design/router-perf-model.rst b/doc/dev/design/router-perf-model.rst index 7ccb63804c..de7bbc59f4 100644 --- a/doc/dev/design/router-perf-model.rst +++ b/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 diff --git a/doc/dev/design/router-port-dispatch.rst b/doc/dev/design/router-port-dispatch.rst index 5c8ee6edbc..efae474529 100644 --- a/doc/dev/design/router-port-dispatch.rst +++ b/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 diff --git a/doc/dev/design/scmp-authentication.rst b/doc/dev/design/scmp-authentication.rst index 77db0a39a7..cf9ef56482 100644 --- a/doc/dev/design/scmp-authentication.rst +++ b/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 ======== diff --git a/doc/dev/design/uri.rst b/doc/dev/design/uri.rst index 5f4fe596e5..6849506ae0 100644 --- a/doc/dev/design/uri.rst +++ b/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 From 5dbb7d0428afe09965d8f826471e2e9e63b62ca0 Mon Sep 17 00:00:00 2001 From: Jean-Christophe Hugly Date: Mon, 30 Sep 2024 12:26:45 +0200 Subject: [PATCH 2/4] Fix punctuation. --- doc/dev/design/scmp-authentication.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/dev/design/scmp-authentication.rst b/doc/dev/design/scmp-authentication.rst index cf9ef56482..cced007745 100644 --- a/doc/dev/design/scmp-authentication.rst +++ b/doc/dev/design/scmp-authentication.rst @@ -7,7 +7,7 @@ SCMP Authentication - Discussion at: :issue:`3969` - Status: **Postponed** -Reason for postponment. No clear consensus that this is the right approach. See "Discussion" section. +Reason for postponment: no clear consensus that this is the right approach. See "Discussion" section. Experimental support in router, added in :issue:`4255`. Abstract From 06115dcdc44792b950a84e205c67d748b8ddf892 Mon Sep 17 00:00:00 2001 From: FR4NK-W Date: Thu, 3 Oct 2024 10:32:48 +0200 Subject: [PATCH 3/4] Fix lint --- doc/dev/contribute.rst | 6 +++--- doc/dev/design/index.rst | 4 ++-- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/doc/dev/contribute.rst b/doc/dev/contribute.rst index fb046e9ead..9c50d59463 100644 --- a/doc/dev/contribute.rst +++ b/doc/dev/contribute.rst @@ -158,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 @@ -173,10 +173,10 @@ Formal Process 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` + 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: - `: finalize design`. + ``: 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. diff --git a/doc/dev/design/index.rst b/doc/dev/design/index.rst index b6686ae71f..c9d66e4d21 100644 --- a/doc/dev/design/index.rst +++ b/doc/dev/design/index.rst @@ -12,7 +12,7 @@ contribution process. 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. @@ -99,7 +99,7 @@ Rejected ======== .. toctree:: :maxdepth: 1 - + .. seealso:: :ref:`change-proposal-process` From 01490296dc2f0b5742d9510fb3b05bc51793d616 Mon Sep 17 00:00:00 2001 From: Jean-Christophe Hugly Date: Thu, 3 Oct 2024 10:52:20 +0200 Subject: [PATCH 4/4] Apply reviewer's suggestion. --- doc/dev/contribute.rst | 4 ++-- doc/dev/design/BeaconService.md | 2 +- doc/dev/design/ColibriService.md | 2 +- doc/dev/design/PathService.md | 2 +- doc/dev/design/TEMPLATE.rst | 2 +- doc/dev/design/forwarding-key-rollover.rst | 2 +- doc/dev/design/index.rst | 2 +- 7 files changed, 8 insertions(+), 8 deletions(-) diff --git a/doc/dev/contribute.rst b/doc/dev/contribute.rst index 9c50d59463..4095430aa2 100644 --- a/doc/dev/contribute.rst +++ b/doc/dev/contribute.rst @@ -138,7 +138,7 @@ More **substantial changes** must be submitted as a **proposal** in the form of a GitHub issue, in order to create a consensus among the SCION community. Typical examples for substantial change proposals include: -* Adding, changing, or removing compontents or functionality +* Adding, changing, or removing components or functionality * Changing interfaces between components Proposals for changes to the SCION protocol (e.g., header format, processing @@ -202,7 +202,7 @@ Formal Process 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 + **Completed**, 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 diff --git a/doc/dev/design/BeaconService.md b/doc/dev/design/BeaconService.md index 1d21ecd71d..11f2e6618d 100644 --- a/doc/dev/design/BeaconService.md +++ b/doc/dev/design/BeaconService.md @@ -1,7 +1,7 @@ # Beacon Service * Author: Lukas Vogel -* Status: **outdated** +* Status: **Outdated** --- ⚠️ **NOTE** ⚠️ diff --git a/doc/dev/design/ColibriService.md b/doc/dev/design/ColibriService.md index cc8b7bd27a..b33301c094 100644 --- a/doc/dev/design/ColibriService.md +++ b/doc/dev/design/ColibriService.md @@ -2,7 +2,7 @@ * Author: Juan A. García Pardo * Last updated: 2020-07-08 -* Status: **outdated**. +* Status: **Outdated**. Prototype was developed in [netsec-ethz/scion:scionlab](https://github.com/netsec-ethz/scion/tree/scionlab) ([commit permalink](https://github.com/netsec-ethz/scion/commit/37a556a4bc494a93fe8294ed77b6f2c9b6192746)), to be replaced with new approach for QoS system. diff --git a/doc/dev/design/PathService.md b/doc/dev/design/PathService.md index f2b0a4d350..d9f6671bcb 100644 --- a/doc/dev/design/PathService.md +++ b/doc/dev/design/PathService.md @@ -1,7 +1,7 @@ # Path Service * Author: Lukas Vogel, Sergiu Costea, Matthias Frei -* Status: **outdated** +* Status: **Outdated** --- ⚠️ **NOTE** ⚠️ diff --git a/doc/dev/design/TEMPLATE.rst b/doc/dev/design/TEMPLATE.rst index fbe94166d2..a3f4b7638e 100644 --- a/doc/dev/design/TEMPLATE.rst +++ b/doc/dev/design/TEMPLATE.rst @@ -5,7 +5,7 @@ - Author(s): [Author Name(s)] - Last updated: [Date (Year-Month-Day)] - Discussion at: :issue:`NNNN` -- Status: [**WIP**, **Active**, **Postponed**, **Rejected**, **Outdated**] +- Status: [**WIP**, **Active**, **Completed**, **Postponed**, **Rejected**, **Outdated**] Abstract ======== diff --git a/doc/dev/design/forwarding-key-rollover.rst b/doc/dev/design/forwarding-key-rollover.rst index 84963ef2fb..b95f0d5b2f 100644 --- a/doc/dev/design/forwarding-key-rollover.rst +++ b/doc/dev/design/forwarding-key-rollover.rst @@ -4,7 +4,7 @@ Forwarding key rollover - Author: Sergiu Costea - Last updated: 2020-09-23 -- Status: **proposal** / **outdated** +- Status: **WIP** / **Outdated** - Discussion at: - This document describes an implementation for key rollover in a SCION AS. diff --git a/doc/dev/design/index.rst b/doc/dev/design/index.rst index c9d66e4d21..a77b15dbda 100644 --- a/doc/dev/design/index.rst +++ b/doc/dev/design/index.rst @@ -32,7 +32,7 @@ contribution process. creating new design documents where appropriate. During implementation the design may also become suspended (**Postponed**) - or abandonned (**Rejected** or **Outdated**). + or abandoned (**Rejected** or **Outdated**). - **Replacement**: If the implementation has changed so much that a design document is no longer