tweaks to dip-0 #206

davidiw · 2021-08-27T00:51:05Z

DIP numbers are assigned by creating an GitHub issue
Cleaned up some white space
Discussions happen in the GitHub issue
Abstract and Summary were extremely redundant especially when the doc
itself tends to be pretty brief if correctly written
Noted which sections are optional more explicitly (backwards
compatibility, test cases)
Made test case requirement more explicit
Implementations is not an invitation to put code into DIPs but rather links to
implementations
We should add a proper copyright notice to each dip

gregnazario · 2021-08-27T01:02:08Z

dips/dip-0.md

@@ -20,8 +21,7 @@ The Diem project operates under the governance of the Diem Association. Technica

 The Lead Maintainer will update the TSC periodically about the progress of DIPs. While technical decisions are supervised by the TSC, day-to-day technical decisions are made using a framework inspired by standards bodies (such as the W3C and IETF) and open source projects (such as Python, the Linux Foundation, and Apache) to coordinate the work of open source contributors. This process is based on the family of approaches derived from Python’s PEP process. The process is supported by a team of Maintainers who work to build consensus on technical decisions. When specifically asked, the Lead Maintainer will bring a DIP to explicit TSC approval and for changing the status of a DIP from “Last Call” to “Accepted” (and eventually, to “Final”).

-The Lead Maintainer is responsible for assigning a Maintainer as DIP Manager for each DIP, assigning a DIP to a Working Group when relevant, and providing the TSC updates on DIPs.
-The DIP Managers are given broad latitude to make decisions on DIP status evolution and outcome, and thus are expected to use best efforts to find consensus among the relevant Diem community members about decisions. While broad latitude granted to DIP Managers is the norm, the DIP process ultimately operates under the authority of the TSC and the Association Council. This authority should generally be applied through constructive conversations with the DIP Managers to engage in a disagree-and-commit decision. The TSC should serve as a resource to community members who feel that a DIP Manager is unfair in their leadership of the DIP process and work to ensure constructive conversation.
+The Lead Maintainer is responsible for assigning a Maintainer as DIP Manager for each DIP, assigning a DIP to a Working Group when relevant, and providing the TSC updates on DIPs.  The DIP Managers are given broad latitude to make decisions on DIP status evolution and outcome, and thus are expected to use best efforts to find consensus among the relevant Diem community members about decisions. While broad latitude granted to DIP Managers is the norm, the DIP process ultimately operates under the authority of the TSC and the Association Council. This authority should generally be applied through constructive conversations with the DIP Managers to engage in a disagree-and-commit decision. The TSC should serve as a resource to community members who feel that a DIP Manager is unfair in their leadership of the DIP process and work to ensure constructive conversation.


Given there isn't really a Lead Maintainer (correct me if I'm wrong) would we just want to say The maintainers are responsible ...

FYI, @dahliamalkhi is the LM.

Unrelated - do we actually want to say here that the LM is responsible for providing TSC updates on the DIPs? That implies that the LM needs to be involved in every DIP and aware of what is happening on every one of them which seems like it won't be scalable forever. Shouldn't we expect the DIP manager to do this at some point?

gregnazario · 2021-08-27T01:03:12Z

dips/dip-0.md

@@ -88,7 +88,7 @@ A change in the author of a DIP can be made at the discretion of the DIP Manager

 ## DIP Discussions

-Discussions about DIPs in progress are best held over pull-requests and reviews in diem/dip. They may optionally use media channels such as the Diem Slack channel or a Discourse thread. In this case, an Author may include a reference to the discussion thread (see below the “discussions-to” header field in the DIP document).
+Discussions about DIPs in progress are best held over pull-requests, reviews in diem/dip, and the issue proposing the DIP. They may optionally use media channels such as the Diem Slack channel or a Discourse thread. In this case, an Author may include a reference to the discussion thread (see below the “discussions-to” header field in the DIP document).


Nit: held in diem/dip over pull-requests, reviews, and the issue proposing the DIP

actually aren't these the same thing 😆

Lol, well this is a minor English nit from the change. The pull requests, reviews, and issues are in diem/dip. But, now it's saying only the reviews are in diem/dip. The original said pull-requests and reviews in diem/dip, referring to both :P

gregnazario · 2021-08-27T01:05:35Z

dips/dip-0.md

-  * Abstract - a short (~200 word) description of the technical issue being addressed.
-  * Motivation (*optional) - The motivation is critical for DIPs that want to change the Diem protocol. It should clearly explain why the existing protocol specification is inadequate to address the problem that the DIP solves. DIP submissions without sufficient motivation may be rejected outright.
+  * Summary - a short (~200 word) description of the DIP.
+  * Motivation\* - The motivation is critical for DIPs that want to change the Diem protocol. It should clearly explain why the existing protocol specification is inadequate to address the problem that the DIP solves. DIP submissions without sufficient motivation may be rejected outright.


So, *s are optional? Just because it's mentioned in DIP Header preamble and not in this section. Might be good to call out.

I think it's great to make this mandatory.

I also agree with @gregnazario that writing out (optional) is more clear.

gregnazario · 2021-08-27T01:06:22Z

dips/dip-0.md

-`requires` header
+### `requires` header


nice, that really bothered me earlier

aching · 2021-08-27T01:53:53Z

dips/dip-0.md

@@ -39,11 +39,11 @@ It is highly recommended that a single DIP should contain a single key proposal

 The formal DIP process will typically (and advisably) begin after the champion of the proposal has already discussed and socialized it with the Diem community (see below for what goes into a DIP). It is comprised of the following steps:

-  * **Idea** – Authors will socialize their idea with the developer community and Maintainers, possibly by writing a GitHub Issue and getting feedback. If possible (and relevant), authors should include in discussions an implementation to support their proposal.
+  * **Idea** – Authors will socialize their idea with the developer community and Maintainers, by writing a GitHub Issue and getting feedback. If possible (and relevant), authors should include in discussions an implementation to support their proposal.


An example DIP (e.g. https://github.com/diem/dip/blob/main/dips/dip-169.md and issue (e.g. #169) would be good to cite.

aching · 2021-08-27T01:55:27Z

dips/dip-0.md

-  * Abstract - a short (~200 word) description of the technical issue being addressed.
-  * Motivation (*optional) - The motivation is critical for DIPs that want to change the Diem protocol. It should clearly explain why the existing protocol specification is inadequate to address the problem that the DIP solves. DIP submissions without sufficient motivation may be rejected outright.
+  * Summary - a short (~200 word) description of the DIP.
+  * Motivation\* - The motivation is critical for DIPs that want to change the Diem protocol. It should clearly explain why the existing protocol specification is inadequate to address the problem that the DIP solves. DIP submissions without sufficient motivation may be rejected outright.


I think it's great to make this mandatory.

I also agree with @gregnazario that writing out (optional) is more clear.

dips/dip-0.md

dahliamalkhi

nice clean up work, thx for doing it. given that we already have DIPs out there that use the new numbering system, it's important to have this update land asap.

dips/dip-0.md

* DIP numbers are assigned by creating an GitHub issue * Cleaned up some white space * Discussions happen in the GitHub issue * Abstract and Summary were extremely redundant especially when the doc itself tends to be pretty brief if correctly written * Noted which sections are optional more explicitly (backwards compatibility, test cases) * Made test case requirement more explicit * Implementations is not an invitation to put code into DIPs but rather links to implementations * We should add a proper copyright notice to each dip

kphfb · 2021-09-16T15:25:41Z

dips/dip-0.md

@@ -20,8 +21,7 @@ The Diem project operates under the governance of the Diem Association. Technica

 The Lead Maintainer will update the TSC periodically about the progress of DIPs. While technical decisions are supervised by the TSC, day-to-day technical decisions are made using a framework inspired by standards bodies (such as the W3C and IETF) and open source projects (such as Python, the Linux Foundation, and Apache) to coordinate the work of open source contributors. This process is based on the family of approaches derived from Python’s PEP process. The process is supported by a team of Maintainers who work to build consensus on technical decisions. When specifically asked, the Lead Maintainer will bring a DIP to explicit TSC approval and for changing the status of a DIP from “Last Call” to “Accepted” (and eventually, to “Final”).

-The Lead Maintainer is responsible for assigning a Maintainer as DIP Manager for each DIP, assigning a DIP to a Working Group when relevant, and providing the TSC updates on DIPs.
-The DIP Managers are given broad latitude to make decisions on DIP status evolution and outcome, and thus are expected to use best efforts to find consensus among the relevant Diem community members about decisions. While broad latitude granted to DIP Managers is the norm, the DIP process ultimately operates under the authority of the TSC and the Association Council. This authority should generally be applied through constructive conversations with the DIP Managers to engage in a disagree-and-commit decision. The TSC should serve as a resource to community members who feel that a DIP Manager is unfair in their leadership of the DIP process and work to ensure constructive conversation.
+The Lead Maintainer is responsible for assigning a Maintainer as DIP Manager for each DIP, assigning a DIP to a Working Group when relevant, and providing the TSC updates on DIPs.  The DIP Managers are given broad latitude to make decisions on DIP status evolution and outcome, and thus are expected to use best efforts to find consensus among the relevant Diem community members about decisions. While broad latitude granted to DIP Managers is the norm, the DIP process ultimately operates under the authority of the TSC and the Association Council. This authority should generally be applied through constructive conversations with the DIP Managers to engage in a disagree-and-commit decision. The TSC should serve as a resource to community members who feel that a DIP Manager is unfair in their leadership of the DIP process and work to ensure constructive conversation.


Unrelated - do we actually want to say here that the LM is responsible for providing TSC updates on the DIPs? That implies that the LM needs to be involved in every DIP and aware of what is happening on every one of them which seems like it won't be scalable forever. Shouldn't we expect the DIP manager to do this at some point?

kphfb · 2021-09-16T15:27:43Z

dips/dip-0.md


-    * ✅ Draft – If agreeable, DIP Manager will assign the DIP a number (generally the issue or PR number related to the DIP, and ask to rename or move to a folder/file with that number) and approve the pull request. The DIP Manager will not unreasonably deny a DIP.
+    * ✅ Draft – If agreeable, the DIP Manager approve the pull request. The DIP Manager will not unreasonably deny a DIP


the DIP Manager approve
to:
the DIP Manager will approve

davidiw requested review from aching, gregnazario, sblackshear, dahliamalkhi and kphfb August 27, 2021 00:51

gregnazario reviewed Aug 27, 2021

View reviewed changes

aching reviewed Aug 27, 2021

View reviewed changes

dahliamalkhi approved these changes Aug 27, 2021

View reviewed changes

dips/dip-0.md Show resolved Hide resolved

davidiw force-pushed the main branch from d182978 to c3d415e Compare August 31, 2021 00:50

davidiw merged commit 5b56351 into diem:main Aug 31, 2021

davidiw deleted the main branch August 31, 2021 00:59

kphfb reviewed Sep 16, 2021

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

tweaks to dip-0 #206

tweaks to dip-0 #206

davidiw commented Aug 27, 2021

gregnazario Aug 27, 2021

aching Aug 27, 2021

kphfb Sep 16, 2021

gregnazario Aug 27, 2021

davidiw Aug 30, 2021

gregnazario Aug 30, 2021 •

edited

Loading

gregnazario Aug 27, 2021

aching Aug 27, 2021

gregnazario Aug 27, 2021

aching Aug 27, 2021

aching Aug 27, 2021

dahliamalkhi left a comment

kphfb Sep 16, 2021

kphfb Sep 16, 2021


		* ✅ Draft – If agreeable, DIP Manager will assign the DIP a number (generally the issue or PR number related to the DIP, and ask to rename or move to a folder/file with that number) and approve the pull request. The DIP Manager will not unreasonably deny a DIP.
		* ✅ Draft – If agreeable, the DIP Manager approve the pull request. The DIP Manager will not unreasonably deny a DIP

tweaks to dip-0 #206

tweaks to dip-0 #206

Conversation

davidiw commented Aug 27, 2021

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

gregnazario Aug 30, 2021 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

dahliamalkhi left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

gregnazario Aug 30, 2021 •

edited

Loading