From c651ecde74ba3fec3a2146b83999f1c403c5eeba Mon Sep 17 00:00:00 2001 From: Martin Thomson Date: Wed, 11 Mar 2020 17:27:21 +1100 Subject: [PATCH 1/9] Remove some more SHOULDs --- draft-ietf-git-using-github.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/draft-ietf-git-using-github.md b/draft-ietf-git-using-github.md index f947d10..5a8239e 100644 --- a/draft-ietf-git-using-github.md +++ b/draft-ietf-git-using-github.md @@ -407,13 +407,13 @@ The user has write access to their own fork, allowing them to make local changes. A pull request asks the owner of a repository to merge a specific set of changes from a fork (or any branch) into their copy. -Editors SHOULD make pull requests for all substantial changes rather than -committing directly to the "master" branch of the repository. See {{mature-documents}} -for discussion on what constitutes a substantial change. A pull request -creates an artifact that records the reasons for changes and provides other -contributors with an opportunity to review the change. Pull requests that -address substantive issues SHOULD mention the issue they address in the opening -comment. +Editors are encouraged to make pull requests for all substantial changes rather +than committing directly to the "master" branch of the repository. See +{{mature-documents}} for discussion on what constitutes a substantial change. A +pull request creates an artifact that records the reasons for changes and +provides other contributors with an opportunity to review the change. Ideally, +pull requests that address substantive issues mention the issue they address in +the opening comment. Note: From 9be1bb9376cde30f0763faa4889ced41a819f605 Mon Sep 17 00:00:00 2001 From: Martin Thomson Date: Wed, 11 Mar 2020 17:29:04 +1100 Subject: [PATCH 2/9] And make it clear that policy might insist upon this --- draft-ietf-git-using-github.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/draft-ietf-git-using-github.md b/draft-ietf-git-using-github.md index 5a8239e..93fbca7 100644 --- a/draft-ietf-git-using-github.md +++ b/draft-ietf-git-using-github.md @@ -413,7 +413,8 @@ than committing directly to the "master" branch of the repository. See pull request creates an artifact that records the reasons for changes and provides other contributors with an opportunity to review the change. Ideally, pull requests that address substantive issues mention the issue they address in -the opening comment. +the opening comment. A Working Group policy could require that pull requests +are used in this fashion. Note: From 583d9072f90395028ff83bcca6da95c977ad109a Mon Sep 17 00:00:00 2001 From: Martin Thomson Date: Wed, 11 Mar 2020 17:31:44 +1100 Subject: [PATCH 3/9] Move text from 5.3 to 5 --- draft-ietf-git-using-github.md | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/draft-ietf-git-using-github.md b/draft-ietf-git-using-github.md index 93fbca7..19604e4 100644 --- a/draft-ietf-git-using-github.md +++ b/draft-ietf-git-using-github.md @@ -494,6 +494,13 @@ models. Working Groups can adjust these policies to suit their needs, but are advised to avoid gratuitous changes for the sake of consistency across the IETF as a whole. +It is possible to use different processes for different documents in the Working +Group. + +Working Group chairs SHOULD confirm that the Working Group has consensus to +adopt any process. In particular, the introduction of a more tightly-controlled +process can have the effect of privileging positions already captured in +documents, which might disadvantage alternative viewpoints. ## Document Management Mode @@ -571,13 +578,7 @@ mailing list, along lines similar to the design team process (see Section 6.5 of {{RFC2418}}). As a more involved process, adopting this mode can require changes in policies -as documents become more mature. It is possible to use different processes for -different documents in the Working Group. - -Working Group chairs SHOULD confirm that the Working Group has consensus to -adopt any process. In particular, the introduction of a more tightly-controlled -process can have the effect of privileging positions already captured in -documents, which might disadvantage alternative viewpoints. +as documents become more mature. ### Early Design Phases From c8120cd97ebe67dea40f6e07d87f6269473ac3f6 Mon Sep 17 00:00:00 2001 From: Martin Thomson Date: Wed, 11 Mar 2020 17:39:45 +1100 Subject: [PATCH 4/9] Adding a SHOULD (wow) --- draft-ietf-git-using-github.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/draft-ietf-git-using-github.md b/draft-ietf-git-using-github.md index 19604e4..908cbfb 100644 --- a/draft-ietf-git-using-github.md +++ b/draft-ietf-git-using-github.md @@ -593,7 +593,8 @@ announce the decision to the Working Group. In many cases, documents that are adopted by a Working Group are already sufficiently mature that a looser process is not beneficial. The primary reason to grant editors more discretionary power is to improve the speed with which changes can be made. The risk is that design -changes might not always reflect the consensus of the Working Group. +changes might not always reflect the consensus of the Working Group or that the +need for consensus on an issue is not identified. Changes made by editors under this process do not completely lack oversight. GitHub and git provide tools for ensuring that changes are tracked and can be @@ -616,7 +617,7 @@ are not made without wider consultation. Chairs might choose to manage the process of deciding which issues are substantive. For instance, chairs might reserve the ability to use the `design` label to new issues (see {{label-design}}) and to close issues marked as `design`. -Chairs should always allow document editors to identify and address editorial +Chairs SHOULD always allow document editors to identify and address editorial issues as they see fit. As documents mature further, explicit confirmation of technical decisions with From 4daefba7410ed2f9298924e6aa28cf3fe9418b52 Mon Sep 17 00:00:00 2001 From: Martin Thomson Date: Wed, 11 Mar 2020 17:49:11 +1100 Subject: [PATCH 5/9] past-WGLC advice with less normative language --- draft-ietf-git-using-github.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/draft-ietf-git-using-github.md b/draft-ietf-git-using-github.md index 908cbfb..35d46cf 100644 --- a/draft-ietf-git-using-github.md +++ b/draft-ietf-git-using-github.md @@ -628,9 +628,10 @@ the abstract, with editors being permitted to capture the outcome of discussions as they see fit. More mature documents require not only consensus, but consensus about specific -text. All substantive changes to documents that have passed WGLC SHOULD be -proposed as pull requests, and MUST be discussed on the mailing list, and MUST -have chairs explicitly confirm consensus. Chairs MAY institute this stricter +text. Ideally, substantive changes to documents that have passed WGLC are +proposed as pull requests, and MUST be discussed on the mailing list. Having +chairs explicitly confirm consensus on changes ensures that previous consensus +decisions are not overturned without cause. Chairs MAY institute this stricter process prior to WGLC. Note: From b6957a6662d9a863592026cc7c2f5e03ac3eb275 Mon Sep 17 00:00:00 2001 From: Martin Thomson Date: Fri, 13 Mar 2020 14:24:08 +1100 Subject: [PATCH 6/9] More transparency, rewording --- draft-ietf-git-using-github.md | 21 +++++++++++---------- 1 file changed, 11 insertions(+), 10 deletions(-) diff --git a/draft-ietf-git-using-github.md b/draft-ietf-git-using-github.md index 35d46cf..c0cdc6f 100644 --- a/draft-ietf-git-using-github.md +++ b/draft-ietf-git-using-github.md @@ -592,16 +592,17 @@ Chairs need to explicitly decide that this sort of process is needed and announce the decision to the Working Group. In many cases, documents that are adopted by a Working Group are already sufficiently mature that a looser process is not beneficial. The primary reason to grant editors more discretionary power -is to improve the speed with which changes can be made. The risk is that design -changes might not always reflect the consensus of the Working Group or that the -need for consensus on an issue is not identified. - -Changes made by editors under this process do not completely lack oversight. -GitHub and git provide tools for ensuring that changes are tracked and can be -audited. Within the usual Working Group process it is expected that -Internet-Drafts will receive regular review. Finally, process checkpoints like -Working Group Last Call (WGLC; Section 7.4 of {{!RFC2418}}) provides additional -safeguards against abuse. +is to improve the speed with which changes can be made. The risk is from +integrating changes including substantive decisions that don't reflect the +consensus of the Working Group or that the need for consensus on an issue is not +identified. + +Changes made by editors under this process do not lack options for identifying +and correcting problems. GitHub and git provide tools for ensuring that changes +are tracked and can be audited. Within the usual Working Group process it is +expected that Internet-Drafts will receive regular review. Finally, process +checkpoints like Working Group Last Call (WGLC; Section 7.4 of {{!RFC2418}}) +provides additional safeguards against abuse. Working Groups are advised against allowing editors this degree of flexibility for the entirety of a document lifecycle. Once a document is more stable and From c86f075cae51c6705d177f32f158160eaf586f99 Mon Sep 17 00:00:00 2001 From: Martin Thomson Date: Fri, 13 Mar 2020 14:25:28 +1100 Subject: [PATCH 7/9] useful as opposed to appropriate --- draft-ietf-git-using-github.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/draft-ietf-git-using-github.md b/draft-ietf-git-using-github.md index c0cdc6f..c78ed77 100644 --- a/draft-ietf-git-using-github.md +++ b/draft-ietf-git-using-github.md @@ -606,7 +606,7 @@ provides additional safeguards against abuse. Working Groups are advised against allowing editors this degree of flexibility for the entirety of a document lifecycle. Once a document is more stable and -mature, it is likely appropriate to move to a more tightly controlled process. +mature, it could be useful to move to a more tightly controlled process. ### Managing Mature Documents {#mature-documents} From 203da8309158390fd72089037a77695c250e650b Mon Sep 17 00:00:00 2001 From: Martin Thomson Date: Fri, 13 Mar 2020 14:26:20 +1100 Subject: [PATCH 8/9] MAY regarding policies --- draft-ietf-git-using-github.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/draft-ietf-git-using-github.md b/draft-ietf-git-using-github.md index c78ed77..4193b49 100644 --- a/draft-ietf-git-using-github.md +++ b/draft-ietf-git-using-github.md @@ -615,7 +615,7 @@ As a document matures, it becomes more important to understand not just that the document as a whole retains the support of the Working Group, but that changes are not made without wider consultation. -Chairs might choose to manage the process of deciding which issues are +Chairs MAY choose to manage the process of deciding which issues are substantive. For instance, chairs might reserve the ability to use the `design` label to new issues (see {{label-design}}) and to close issues marked as `design`. Chairs SHOULD always allow document editors to identify and address editorial From 17cf7f64158797f8afd11640a05449d7f4bad1c1 Mon Sep 17 00:00:00 2001 From: Martin Thomson Date: Fri, 13 Mar 2020 14:36:07 +1100 Subject: [PATCH 9/9] Discussion venues and consensus --- draft-ietf-git-using-github.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/draft-ietf-git-using-github.md b/draft-ietf-git-using-github.md index 4193b49..6ea6a66 100644 --- a/draft-ietf-git-using-github.md +++ b/draft-ietf-git-using-github.md @@ -770,9 +770,10 @@ of the document. Other participants might not use GitHub at all. Chairs are reminded that assessing consensus based on GitHub content alone cannot be assumed to reach all interested participants. -Chairs MUST consider input from all discussion venues when assessing consensus -including GitHub, mailing lists, interim meetings, and IETF meetings. Each venue -has different selection biases that might need to be considered. +As described in {{!RFC2418}}, chairs consider input from all discussion venues +when assessing consensus. These include mailing lists, IETF meetings, and +interim meetings in addition to discussion on GitHub. Each venue has different +selection biases that might need to be considered. A Working Group chair MUST consult the Working Group mailing list for any issue that is potentially contentious. Relying on input provided through GitHub alone