From 31bd50c0111fbadba9551e70bea0b38dbe15984a Mon Sep 17 00:00:00 2001 From: Ryan Richard Date: Mon, 24 Jan 2022 15:17:09 -0800 Subject: [PATCH 01/10] first draft of proposal process --- GOVERNANCE.md | 170 ++++++++++++++++++++++++++++++++++++++------ proposals/README.md | 8 +++ 2 files changed, 158 insertions(+), 20 deletions(-) create mode 100644 proposals/README.md diff --git a/GOVERNANCE.md b/GOVERNANCE.md index 679648f6c..05c674b83 100644 --- a/GOVERNANCE.md +++ b/GOVERNANCE.md @@ -1,18 +1,14 @@ # Pinniped Governance - This document defines the project governance for Pinniped. # Overview - **Pinniped** is committed to building an open, inclusive, productive and self-governing open source community focused on building authentication services for Kubernetes clusters. The community is governed by this document which defines how all members should work together to achieve this goal. # Code of Conduct - The Pinniped community abides by this [code of conduct](https://github.com/vmware-tanzu/pinniped/blob/main/CODE_OF_CONDUCT.md). # Community Roles - * **Users:** Members that engage with the Pinniped community via any medium (Slack, GitHub, mailing lists, etc.). * **Contributors:** Do regular contributions to the Pinniped project (documentation, code reviews, responding to issues, participating in proposal discussions, contributing code, etc.). * **Maintainers:** Responsible for the overall health and direction of the project. They are the final reviewers of PRs and responsible for Pinniped releases. @@ -22,30 +18,164 @@ New maintainers must be nominated by an existing maintainer and must be elected **Note:** If a maintainer leaves their employer they are still considered a maintainer of Pinniped, unless they voluntarily resign. Employment is not taken into consideration when determining maintainer eligibility unless the company itself violates our [Code of Conduct](https://github.com/vmware-tanzu/pinniped/blob/main/CODE_OF_CONDUCT.md). ---- -# Supermajority -A supermajority is defined as two-thirds of members in the group. A supermajority of Maintainers is required for certain decisions as outlined above. A supermajority vote is equivalent to the number of votes in favor of being at least twice the number of votes against. For example, if you have 5 maintainers, a supermajority vote is 4 votes. Voting on decisions can happen on the mailing list, GitHub, Slack, email, or via a voting service, when appropriate. Maintainers can either vote "agree, yes, +1", "disagree, no, -1", or "abstain". A vote passes when supermajority is met. An abstain vote equals not voting at all. - ---- # Decision Making Ideally, all project decisions are resolved by consensus. If impossible, any maintainer may call a vote. Unless otherwise specified in this document, any vote will be decided by a supermajority of maintainers. ---- -# Proposal Process -The proposal process is currently being worked on. No formal process is available at this time. You may reach out to the maintainers in the Kubernetes Slack Workspace within the [#pinniped](https://kubernetes.slack.com/archives/C01BW364RJA) channel or on the [Pinniped mailing list](project-pinniped@googlegroups.com) with any questions you may have or to send us your proposals. +## Supermajority +A supermajority is defined as two-thirds of members in the group. A supermajority of maintainers is required for certain decisions as outlined in this document. A supermajority vote is equivalent to the number of votes in favor being at least twice the number of votes against. A vote to abstain equals not voting at all. For example, if you have 5 maintainers who all cast non-abstaining votes, then a supermajority vote is at least 4 votes in favor. Voting on decisions can happen on the mailing list, GitHub, Slack, email, or via a voting service, when appropriate. Maintainers can either vote "agree, yes, +1", "disagree, no, -1", or "abstain". A vote passes when supermajority is met. ---- -# Lazy Consensus -To maintain velocity in Pinniped, the concept of [Lazy Consensus](http://en.osswiki.info/concepts/lazy_consensus) is practiced. Ideas and / or proposals should be shared by maintainers via GitHub. Out of respect for other contributors, major changes should also be accompanied by a ping on the Kubernetes Slack in [#Pinniped](https://kubernetes.slack.com/archives/C01BW364RJA) or a note on the [Pinniped mailing list](project-pinniped@googlegroups.com) as appropriate. Author(s) of proposals for major changes will give a time period of no less than five (5) working days for comment and remain cognizant of popular observed world holidays. - -**What constitutes the need for a proposal?** -If there is significant risk with a potential feature or track of work (such as complexity, cost to implement, product viability, etc.), then we recommend creating a proposal for feedback and approval. If a potential feature is well understood and doesn't impose risk, then we recommend a **standard GitHub issue** to clarify the details. +## Lazy Consensus +To maintain velocity in Pinniped, the concept of [Lazy Consensus](http://en.osswiki.info/concepts/lazy_consensus) is practiced. Other maintainers may chime in and request additional time for review, but should remain cognizant of blocking progress and abstain from delaying progress unless absolutely needed. The expectation is that blocking progress is accompanied by a guarantee to review and respond to the relevant action in short order. Lazy consensus does not apply to the process of: * Removal of maintainers from Pinniped +## Updating Governance +All substantive changes in Governance, including substantive changes to the proposal process, require a supermajority agreement by all maintainers. + +# Proposal Process +A proposal is a design document that describes a significant change to Pinniped. +A proposal must be sponsored (or co-authored) by at least one maintainer. +Proposals can be submitted and reviewed by anyone in the community. + +The purpose of a proposal is to build consensus on a problem statement and solution design before starting work on the implementation. + +## When to Submit a Proposal +If there is significant risk with a potential feature or track of work (such as complexity, cost to implement, +product viability, etc.), then we recommend creating a proposal for feedback and approval. If a potential +feature is well understood and doesn't impose risk, then we recommend a standard GitHub issue to clarify the details. + +If you are considering creating a PR to change Pinniped's source code, and you are not sure if the change is +significant enough to require using the proposal process, then please ask the maintainers. + +If you would like to simply share a problem that you are having, or share an idea for a potential feature, +and you are not planning on designing a technical solution or submitting an implementation PR, then please feel free +to create a standard GitHub issue instead of using the proposal process. + +## How to Submit a Proposal +To create a proposal, submit a PR to this repo introducing a new subdirectory under the `proposals` directory +with a terse name (for example, `0001_my-feature-name/`) prefixed by a monotonically incrementing proposal number. +In that new subdirectory, create a `README.md` containing the core proposal. +Include other files as necessary to help support understanding of the feature. + +To make your new proposal know to all other contributors, please send a link to your new proposal PR +on the Kubernetes Slack in [#pinniped](https://kubernetes.slack.com/archives/C01BW364RJA) +or via the [Pinniped mailing list](mailto:project-pinniped@googlegroups.com). + +Author(s) of proposals for major changes will give a time period of no less than five (5) working days +for comment and remain cognizant of popular observed world holidays. + +A proposal must be sponsored (or co-authored) by at least one maintainer. +If you need to find a maintainer to sponsor your proposal, then reach out via Slack or the mailing list +with a description of the problem statement. If one or more of the maintainers agrees that the problem +statement is within the scope of the project (see [SCOPE.md](SCOPE.md)) and is appropriate to be addressed by a proposal, +then a maintainer will be assigned as your proposal's sponsor. The sponsor can provide you with support during +the drafting of the proposal, including sharing additional project and roadmap context as it relates to your +problem statement, answering questions, giving feedback, etc. + +### Proposal Template +The below template is an example `README.md` for a new proposal. +Other than the high-level details at the top of the template (title, status, author, and sponsor), +please use whichever sections make the most sense for your proposal. + +```md --- -# Updating Governance -All substantive changes in Governance require a supermajority agreement by all maintainers. \ No newline at end of file +title: "The Name of My Proposal" +authors: [ "@margocrawf", "@enj" ] +status: "draft" +sponsor: [ "@cfryanr" ] +--- + +# + +## Problem Statement +This is a short summary of the problem that exists, why it needs to be +solved: what specific needs are being met. Compelling problem statements +include concrete examples and use cases (even if only by reference). +How exactly the proposal would meet those needs should be located in the +"Proposal" section, not this one. The goal of this section is to help +readers quickly empathize with the target users' current experience to +motivate the proposed change. + +### How Pinniped Works Today (as of version vX.X.X) +How Pinniped works today in the context of the problem statement. +This will typically detail how Pinniped falls short of supporting +the desired use case(s). + +## Terminology / Concepts +Define any terms or concepts that are used throughout this proposal. + +## Proposal +The primary content of the proposal. Subsections will explain how the +problem(s) will be addressed. + +### Goals and Non-goals +A short list of what the goals of this proposal are and are not. + +### Specification / How it Solves the Use Cases +Detailed explanation of the proposal's design. This will typically +also detail how the specification supports the desired use cases. + +### Other Approaches Considered +Mention of other reasonable ways that the problem(s) +could be addressed with rationale for why they were less +desirable than the proposed approach. + +## Open Questions +A list of questions that need to be answered. + +## Answered Questions +A list of questions that have been answered. +``` + +## Proposal States +| Status | Definition | +| --- | --- | +| `draft` | The proposal is actively being written by the proposer. Not yet ready for review. | +| `in-review` | The proposal is being reviewed by the community and the project maintainers. | +| `accepted` | The proposal has been accepted by the project maintainers. | +| `rejected` | The proposal has been rejected by the project maintainers. | + +## Lifecycle of a Proposal +1. Author adds a proposal by creating a PR in draft mode. (Authors can save their work until ready.) +2. When the author elaborates the proposal sufficiently to withstand critique they: + 1. change the status to `in-review` and + 2. mark the PR as "Ready for Review" +3. The community critiques the proposal by adding PR reviews in order to mature/converge on the proposal. +4. When the maintainers reach consensus or supermajority to accept a proposal, they: + 1. change the status to `accepted`, + 2. adjust the proposal number in the subdirectory's name if needed, + 3. record both majority and dissenting opinions, + 4. merge the PR, thus adding the new proposal to the `main` branch, and + 5. code implementation PR(s) are submitted separately to implement the solution. +5. When the maintainers do not reach consensus or supermajority, then the proposal is rejected, and they: + 1. may mark the status `rejected`, and + 2. close the PR with a note explaining the rejection. +6. Rejected proposal PRs may be reopened and moved back to `in-review` if there are material changes to the proposal which address the reasons for rejection. + +## Proposal Review +Once a proposal PR marked as "Ready for Review", the community and all project maintainers will review the proposal. +The goal of the review is to gain an understanding of the problem being solved and the design of the proposed solution. + +Maintainers will consider all aspects of the proposed problem and solution, including but not limited to: +- Is the problem within scope for the project? +- Would the additional future cost of maintenance imposed by an implementation of the solution justify solving the problem? +- Is the solution reasonably consistent with the rest of the project? +- How does the solution impact the usability, security, scalability, performance, observability, and reliability of Pinniped? +- How might an implementation of the solution be architected and tested via automation? +- What risks might be introduced by an implementation of the solution? +- The opportunity cost of the time it would take to implement the solution, if the implementation is to be done by the maintainers. + +## Maintenance of Accepted Proposal Documents +Proposal documents reflect a point-in-time design and decision. +Once approved, they become historical documents, not living documents. +There is no expectation that they will be maintained in the future. Instead, significant changes to a feature +which came from a previous proposal should be proposed as a fresh proposal. New proposals should link +to previous proposals for historical context when appropriate. + +## Getting Help with the Proposal Process +Please reach out to the maintainers in the Kubernetes Slack Workspace within +the [#pinniped](https://kubernetes.slack.com/archives/C01BW364RJA) channel +or on the [Pinniped mailing list](mailto:project-pinniped@googlegroups.com) with any questions. diff --git a/proposals/README.md b/proposals/README.md new file mode 100644 index 000000000..237ccdaf3 --- /dev/null +++ b/proposals/README.md @@ -0,0 +1,8 @@ +# Proposals + +This directory contains proposal documents for significant enhancements and changes to Pinniped. + +For information about how and when to submit a proposal, see [GOVERNANCE.md](../GOVERNANCE.md). + +Note that prior to early 2022, proposal documents were written as public Google Docs or Hackmd docs, +so they were not stored here. From e9e56689cf00a480ec1f12cba1441b3dc4f9e092 Mon Sep 17 00:00:00 2001 From: Ryan Richard Date: Tue, 25 Jan 2022 11:22:19 -0800 Subject: [PATCH 02/10] Update draft proposal process based on feedback --- GOVERNANCE.md | 82 +++++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 70 insertions(+), 12 deletions(-) diff --git a/GOVERNANCE.md b/GOVERNANCE.md index 05c674b83..a18c8391d 100644 --- a/GOVERNANCE.md +++ b/GOVERNANCE.md @@ -36,12 +36,11 @@ Lazy consensus does not apply to the process of: All substantive changes in Governance, including substantive changes to the proposal process, require a supermajority agreement by all maintainers. # Proposal Process +The purpose of a proposal is to build consensus on a problem statement and solution design before starting work on the implementation. A proposal is a design document that describes a significant change to Pinniped. A proposal must be sponsored (or co-authored) by at least one maintainer. Proposals can be submitted and reviewed by anyone in the community. -The purpose of a proposal is to build consensus on a problem statement and solution design before starting work on the implementation. - ## When to Submit a Proposal If there is significant risk with a potential feature or track of work (such as complexity, cost to implement, product viability, etc.), then we recommend creating a proposal for feedback and approval. If a potential @@ -60,15 +59,14 @@ with a terse name (for example, `0001_my-feature-name/`) prefixed by a monotonic In that new subdirectory, create a `README.md` containing the core proposal. Include other files as necessary to help support understanding of the feature. -To make your new proposal know to all other contributors, please send a link to your new proposal PR +To make your new proposal known to all other contributors, please send a link to your new proposal PR on the Kubernetes Slack in [#pinniped](https://kubernetes.slack.com/archives/C01BW364RJA) or via the [Pinniped mailing list](mailto:project-pinniped@googlegroups.com). Author(s) of proposals for major changes will give a time period of no less than five (5) working days for comment and remain cognizant of popular observed world holidays. -A proposal must be sponsored (or co-authored) by at least one maintainer. -If you need to find a maintainer to sponsor your proposal, then reach out via Slack or the mailing list +If you don't already have a maintainer to sponsor your proposal, then reach out via Slack or the mailing list with a description of the problem statement. If one or more of the maintainers agrees that the problem statement is within the scope of the project (see [SCOPE.md](SCOPE.md)) and is appropriate to be addressed by a proposal, then a maintainer will be assigned as your proposal's sponsor. The sponsor can provide you with support during @@ -77,8 +75,8 @@ problem statement, answering questions, giving feedback, etc. ### Proposal Template The below template is an example `README.md` for a new proposal. -Other than the high-level details at the top of the template (title, status, author, and sponsor), -please use whichever sections make the most sense for your proposal. +Other than the high-level details at the top of the template (title, authors, status, sponsor, and approval_date) +and the disclaimer at the top, please use whichever sections make the most sense for your proposal. ```md --- @@ -86,8 +84,14 @@ title: "The Name of My Proposal" authors: [ "@margocrawf", "@enj" ] status: "draft" sponsor: [ "@cfryanr" ] +approval_date: "" --- +*Disclaimer*: Proposals are point-in-time designs and decisions. +Once approved and implemented, they become historical documents. +If you are reading an old proposal, please be aware that the +features described herein might have continued to evolve since. + # ## Problem Statement @@ -118,6 +122,44 @@ A short list of what the goals of this proposal are and are not. Detailed explanation of the proposal's design. This will typically also detail how the specification supports the desired use cases. +#### API Changes +Describe how Pinniped's API will change. APIs include CLI commands, +HTTP endpoints, aggregated API endpoints, CRDs, etc. +Detail changes to their inputs, outputs, and behavior. + +#### Upgrades +Describe how upgrading to a new version of Pinniped which includes +these features would work. Are the new changes backwards compatible? +Can new and old versions of the CLI and servers be mixed? +Will it be possible to downgrade after upgrading? + +#### Tests +What kind of integration tests could be used to test the new features? + +#### New Dependencies +Would any significant new project dependencies be needed to support +the implementation? Consider Golang libraries, CI infrastructure, etc. + +#### Performance Considerations +Any concerns with scalability, performance, or reliability for the +implementation? + +#### Observability Considerations +Any new log statements or other considerations to make this feature +observable and debuggable for admin users? + +#### Security Considerations +How does the proposal consider security? What makes the new features +secure? + +#### Usability Considerations +How does the proposal consider usability for the end user (kubectl user) +and for the admin user who installs and configures Pinniped? + +#### Documentation Considerations +How will users discover the new features? Will docs changes be required +during implementation? + ### Other Approaches Considered Mention of other reasonable ways that the problem(s) could be addressed with rationale for why they were less @@ -128,6 +170,17 @@ A list of questions that need to be answered. ## Answered Questions A list of questions that have been answered. + +## Implementation Plan +Who will implement this proposal once it is finished and approved? +Do you already have ideas for how you might approach the implementation +in an iterative fashion? + +## Implementation PRs +This section is a placeholder to list the PRs that implement this proposal. +This section should be left empty until after the proposal is approved. +After implementation, the proposal can be updated to list related +implementation PRs. ``` ## Proposal States @@ -137,23 +190,28 @@ A list of questions that have been answered. | `in-review` | The proposal is being reviewed by the community and the project maintainers. | | `accepted` | The proposal has been accepted by the project maintainers. | | `rejected` | The proposal has been rejected by the project maintainers. | +| `implemented` | The proposal was accepted and has since been implemented. | ## Lifecycle of a Proposal 1. Author adds a proposal by creating a PR in draft mode. (Authors can save their work until ready.) 2. When the author elaborates the proposal sufficiently to withstand critique they: 1. change the status to `in-review` and - 2. mark the PR as "Ready for Review" + 2. mark the PR as "Ready for Review". 3. The community critiques the proposal by adding PR reviews in order to mature/converge on the proposal. 4. When the maintainers reach consensus or supermajority to accept a proposal, they: 1. change the status to `accepted`, 2. adjust the proposal number in the subdirectory's name if needed, 3. record both majority and dissenting opinions, - 4. merge the PR, thus adding the new proposal to the `main` branch, and - 5. code implementation PR(s) are submitted separately to implement the solution. -5. When the maintainers do not reach consensus or supermajority, then the proposal is rejected, and they: + 4. merge the PR, thus adding the new proposal to the `main` branch, + 5. code implementation PRs are submitted separately to implement the solution. +5. During implementation of an accepted proposal: + 1. if it is discovered that significant unanticipated changes are needed to the proposal, then the implementation work should + be paused and the proposal should be updated with the new details to be reviewed by the maintainers again before resuming implementation, and + 2. when all implementation PRs are merged, the proposal doc should be updated to have status `implemented` and to list the related PRs. +6. When the maintainers do not reach consensus or supermajority, then the proposal is rejected, and they: 1. may mark the status `rejected`, and 2. close the PR with a note explaining the rejection. -6. Rejected proposal PRs may be reopened and moved back to `in-review` if there are material changes to the proposal which address the reasons for rejection. +7. Rejected proposal PRs may be reopened and moved back to `in-review` if there are material changes to the proposal which address the reasons for rejection. ## Proposal Review Once a proposal PR marked as "Ready for Review", the community and all project maintainers will review the proposal. From d4725423a984f4853fa32e3a31008bf7e491f872 Mon Sep 17 00:00:00 2001 From: Ryan Richard Date: Thu, 27 Jan 2022 14:51:52 -0800 Subject: [PATCH 03/10] More updates to draft proposal process based on feedback --- GOVERNANCE.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/GOVERNANCE.md b/GOVERNANCE.md index a18c8391d..c29390aaa 100644 --- a/GOVERNANCE.md +++ b/GOVERNANCE.md @@ -126,6 +126,7 @@ also detail how the specification supports the desired use cases. Describe how Pinniped's API will change. APIs include CLI commands, HTTP endpoints, aggregated API endpoints, CRDs, etc. Detail changes to their inputs, outputs, and behavior. +What will the default values be for any new fields or parameters? #### Upgrades Describe how upgrading to a new version of Pinniped which includes @@ -174,7 +175,8 @@ A list of questions that have been answered. ## Implementation Plan Who will implement this proposal once it is finished and approved? Do you already have ideas for how you might approach the implementation -in an iterative fashion? +in an iterative fashion? For a large proposal with an iterative plan, +where might you draw the line to define a minimum viable version? ## Implementation PRs This section is a placeholder to list the PRs that implement this proposal. From a2a05548f9711c6f100e25f1eb389101a9e3fccc Mon Sep 17 00:00:00 2001 From: Ryan Richard Date: Thu, 27 Jan 2022 14:56:10 -0800 Subject: [PATCH 04/10] More updates to draft proposal process based on feedback --- GOVERNANCE.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/GOVERNANCE.md b/GOVERNANCE.md index c29390aaa..0474448dc 100644 --- a/GOVERNANCE.md +++ b/GOVERNANCE.md @@ -121,6 +121,8 @@ A short list of what the goals of this proposal are and are not. ### Specification / How it Solves the Use Cases Detailed explanation of the proposal's design. This will typically also detail how the specification supports the desired use cases. +If some use cases or parts of some use cases are being deferred +to a future proposal, that might be mentioned here as well. #### API Changes Describe how Pinniped's API will change. APIs include CLI commands, From 26dcbd9ec1d05c7330b766ce1359f73be7abd011 Mon Sep 17 00:00:00 2001 From: Ryan Richard Date: Mon, 14 Feb 2022 13:45:30 -0800 Subject: [PATCH 05/10] Try using ```markdown instead of ```md for coloring --- GOVERNANCE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/GOVERNANCE.md b/GOVERNANCE.md index 0474448dc..6bb784ec4 100644 --- a/GOVERNANCE.md +++ b/GOVERNANCE.md @@ -78,7 +78,7 @@ The below template is an example `README.md` for a new proposal. Other than the high-level details at the top of the template (title, authors, status, sponsor, and approval_date) and the disclaimer at the top, please use whichever sections make the most sense for your proposal. -```md +```markdown --- title: "The Name of My Proposal" authors: [ "@margocrawf", "@enj" ] From 42db13d0443cdbd1639292a1fb0fe82260775736 Mon Sep 17 00:00:00 2001 From: Ryan Richard Date: Tue, 15 Feb 2022 10:14:59 -0800 Subject: [PATCH 06/10] Move the proposal process doc to the `proposals` directory's README.md --- GOVERNANCE.md | 206 +--------------------------------------- proposals/README.md | 226 +++++++++++++++++++++++++++++++++++++++++++- 2 files changed, 224 insertions(+), 208 deletions(-) diff --git a/GOVERNANCE.md b/GOVERNANCE.md index 6bb784ec4..3a7b7fb45 100644 --- a/GOVERNANCE.md +++ b/GOVERNANCE.md @@ -36,208 +36,4 @@ Lazy consensus does not apply to the process of: All substantive changes in Governance, including substantive changes to the proposal process, require a supermajority agreement by all maintainers. # Proposal Process -The purpose of a proposal is to build consensus on a problem statement and solution design before starting work on the implementation. -A proposal is a design document that describes a significant change to Pinniped. -A proposal must be sponsored (or co-authored) by at least one maintainer. -Proposals can be submitted and reviewed by anyone in the community. - -## When to Submit a Proposal -If there is significant risk with a potential feature or track of work (such as complexity, cost to implement, -product viability, etc.), then we recommend creating a proposal for feedback and approval. If a potential -feature is well understood and doesn't impose risk, then we recommend a standard GitHub issue to clarify the details. - -If you are considering creating a PR to change Pinniped's source code, and you are not sure if the change is -significant enough to require using the proposal process, then please ask the maintainers. - -If you would like to simply share a problem that you are having, or share an idea for a potential feature, -and you are not planning on designing a technical solution or submitting an implementation PR, then please feel free -to create a standard GitHub issue instead of using the proposal process. - -## How to Submit a Proposal -To create a proposal, submit a PR to this repo introducing a new subdirectory under the `proposals` directory -with a terse name (for example, `0001_my-feature-name/`) prefixed by a monotonically incrementing proposal number. -In that new subdirectory, create a `README.md` containing the core proposal. -Include other files as necessary to help support understanding of the feature. - -To make your new proposal known to all other contributors, please send a link to your new proposal PR -on the Kubernetes Slack in [#pinniped](https://kubernetes.slack.com/archives/C01BW364RJA) -or via the [Pinniped mailing list](mailto:project-pinniped@googlegroups.com). - -Author(s) of proposals for major changes will give a time period of no less than five (5) working days -for comment and remain cognizant of popular observed world holidays. - -If you don't already have a maintainer to sponsor your proposal, then reach out via Slack or the mailing list -with a description of the problem statement. If one or more of the maintainers agrees that the problem -statement is within the scope of the project (see [SCOPE.md](SCOPE.md)) and is appropriate to be addressed by a proposal, -then a maintainer will be assigned as your proposal's sponsor. The sponsor can provide you with support during -the drafting of the proposal, including sharing additional project and roadmap context as it relates to your -problem statement, answering questions, giving feedback, etc. - -### Proposal Template -The below template is an example `README.md` for a new proposal. -Other than the high-level details at the top of the template (title, authors, status, sponsor, and approval_date) -and the disclaimer at the top, please use whichever sections make the most sense for your proposal. - -```markdown ---- -title: "The Name of My Proposal" -authors: [ "@margocrawf", "@enj" ] -status: "draft" -sponsor: [ "@cfryanr" ] -approval_date: "" ---- - -*Disclaimer*: Proposals are point-in-time designs and decisions. -Once approved and implemented, they become historical documents. -If you are reading an old proposal, please be aware that the -features described herein might have continued to evolve since. - -# - -## Problem Statement -This is a short summary of the problem that exists, why it needs to be -solved: what specific needs are being met. Compelling problem statements -include concrete examples and use cases (even if only by reference). -How exactly the proposal would meet those needs should be located in the -"Proposal" section, not this one. The goal of this section is to help -readers quickly empathize with the target users' current experience to -motivate the proposed change. - -### How Pinniped Works Today (as of version vX.X.X) -How Pinniped works today in the context of the problem statement. -This will typically detail how Pinniped falls short of supporting -the desired use case(s). - -## Terminology / Concepts -Define any terms or concepts that are used throughout this proposal. - -## Proposal -The primary content of the proposal. Subsections will explain how the -problem(s) will be addressed. - -### Goals and Non-goals -A short list of what the goals of this proposal are and are not. - -### Specification / How it Solves the Use Cases -Detailed explanation of the proposal's design. This will typically -also detail how the specification supports the desired use cases. -If some use cases or parts of some use cases are being deferred -to a future proposal, that might be mentioned here as well. - -#### API Changes -Describe how Pinniped's API will change. APIs include CLI commands, -HTTP endpoints, aggregated API endpoints, CRDs, etc. -Detail changes to their inputs, outputs, and behavior. -What will the default values be for any new fields or parameters? - -#### Upgrades -Describe how upgrading to a new version of Pinniped which includes -these features would work. Are the new changes backwards compatible? -Can new and old versions of the CLI and servers be mixed? -Will it be possible to downgrade after upgrading? - -#### Tests -What kind of integration tests could be used to test the new features? - -#### New Dependencies -Would any significant new project dependencies be needed to support -the implementation? Consider Golang libraries, CI infrastructure, etc. - -#### Performance Considerations -Any concerns with scalability, performance, or reliability for the -implementation? - -#### Observability Considerations -Any new log statements or other considerations to make this feature -observable and debuggable for admin users? - -#### Security Considerations -How does the proposal consider security? What makes the new features -secure? - -#### Usability Considerations -How does the proposal consider usability for the end user (kubectl user) -and for the admin user who installs and configures Pinniped? - -#### Documentation Considerations -How will users discover the new features? Will docs changes be required -during implementation? - -### Other Approaches Considered -Mention of other reasonable ways that the problem(s) -could be addressed with rationale for why they were less -desirable than the proposed approach. - -## Open Questions -A list of questions that need to be answered. - -## Answered Questions -A list of questions that have been answered. - -## Implementation Plan -Who will implement this proposal once it is finished and approved? -Do you already have ideas for how you might approach the implementation -in an iterative fashion? For a large proposal with an iterative plan, -where might you draw the line to define a minimum viable version? - -## Implementation PRs -This section is a placeholder to list the PRs that implement this proposal. -This section should be left empty until after the proposal is approved. -After implementation, the proposal can be updated to list related -implementation PRs. -``` - -## Proposal States -| Status | Definition | -| --- | --- | -| `draft` | The proposal is actively being written by the proposer. Not yet ready for review. | -| `in-review` | The proposal is being reviewed by the community and the project maintainers. | -| `accepted` | The proposal has been accepted by the project maintainers. | -| `rejected` | The proposal has been rejected by the project maintainers. | -| `implemented` | The proposal was accepted and has since been implemented. | - -## Lifecycle of a Proposal -1. Author adds a proposal by creating a PR in draft mode. (Authors can save their work until ready.) -2. When the author elaborates the proposal sufficiently to withstand critique they: - 1. change the status to `in-review` and - 2. mark the PR as "Ready for Review". -3. The community critiques the proposal by adding PR reviews in order to mature/converge on the proposal. -4. When the maintainers reach consensus or supermajority to accept a proposal, they: - 1. change the status to `accepted`, - 2. adjust the proposal number in the subdirectory's name if needed, - 3. record both majority and dissenting opinions, - 4. merge the PR, thus adding the new proposal to the `main` branch, - 5. code implementation PRs are submitted separately to implement the solution. -5. During implementation of an accepted proposal: - 1. if it is discovered that significant unanticipated changes are needed to the proposal, then the implementation work should - be paused and the proposal should be updated with the new details to be reviewed by the maintainers again before resuming implementation, and - 2. when all implementation PRs are merged, the proposal doc should be updated to have status `implemented` and to list the related PRs. -6. When the maintainers do not reach consensus or supermajority, then the proposal is rejected, and they: - 1. may mark the status `rejected`, and - 2. close the PR with a note explaining the rejection. -7. Rejected proposal PRs may be reopened and moved back to `in-review` if there are material changes to the proposal which address the reasons for rejection. - -## Proposal Review -Once a proposal PR marked as "Ready for Review", the community and all project maintainers will review the proposal. -The goal of the review is to gain an understanding of the problem being solved and the design of the proposed solution. - -Maintainers will consider all aspects of the proposed problem and solution, including but not limited to: -- Is the problem within scope for the project? -- Would the additional future cost of maintenance imposed by an implementation of the solution justify solving the problem? -- Is the solution reasonably consistent with the rest of the project? -- How does the solution impact the usability, security, scalability, performance, observability, and reliability of Pinniped? -- How might an implementation of the solution be architected and tested via automation? -- What risks might be introduced by an implementation of the solution? -- The opportunity cost of the time it would take to implement the solution, if the implementation is to be done by the maintainers. - -## Maintenance of Accepted Proposal Documents -Proposal documents reflect a point-in-time design and decision. -Once approved, they become historical documents, not living documents. -There is no expectation that they will be maintained in the future. Instead, significant changes to a feature -which came from a previous proposal should be proposed as a fresh proposal. New proposals should link -to previous proposals for historical context when appropriate. - -## Getting Help with the Proposal Process -Please reach out to the maintainers in the Kubernetes Slack Workspace within -the [#pinniped](https://kubernetes.slack.com/archives/C01BW364RJA) channel -or on the [Pinniped mailing list](mailto:project-pinniped@googlegroups.com) with any questions. +The proposal process is defined in [proposals/README.md](proposals/README.md). diff --git a/proposals/README.md b/proposals/README.md index 237ccdaf3..cd7571d7f 100644 --- a/proposals/README.md +++ b/proposals/README.md @@ -2,7 +2,227 @@ This directory contains proposal documents for significant enhancements and changes to Pinniped. -For information about how and when to submit a proposal, see [GOVERNANCE.md](../GOVERNANCE.md). +Note that prior to early 2022, proposal documents were written as public Google Docs or Hackmd docs, so they were not +stored here. -Note that prior to early 2022, proposal documents were written as public Google Docs or Hackmd docs, -so they were not stored here. +# Proposal Process + +The purpose of a proposal is to build consensus on a problem statement and solution design before starting work on the +implementation. A proposal is a design document that describes a significant change to Pinniped. A proposal must be +sponsored (or co-authored) by at least one maintainer. Proposals can be submitted and reviewed by anyone in the +community. + +## When to Submit a Proposal + +If there is significant risk with a potential feature or track of work (such as complexity, cost to implement, product +viability, etc.), then we recommend creating a proposal for feedback and approval. If a potential feature is well +understood and doesn't impose risk, then we recommend a standard GitHub issue to clarify the details. + +If you are considering creating a PR to change Pinniped's source code, and you are not sure if the change is significant +enough to require using the proposal process, then please ask the maintainers. + +If you would like to simply share a problem that you are having, or share an idea for a potential feature, and you are +not planning on designing a technical solution or submitting an implementation PR, then please feel free to create a +standard GitHub issue instead of using the proposal process. + +## How to Submit a Proposal + +To create a proposal, submit a PR to this repo introducing a new subdirectory under the `proposals` directory with a +terse name (for example, `0001_my-feature-name/`) prefixed by a monotonically incrementing proposal number. In that new +subdirectory, create a `README.md` containing the core proposal. Include other files as necessary to help support +understanding of the feature. + +To make your new proposal known to all other contributors, please send a link to your new proposal PR on the Kubernetes +Slack in [#pinniped](https://kubernetes.slack.com/archives/C01BW364RJA) +or via the [Pinniped mailing list](mailto:project-pinniped@googlegroups.com). + +Author(s) of proposals for major changes will give a time period of no less than five (5) working days for comment and +remain cognizant of popular observed world holidays. + +If you don't already have a maintainer to sponsor your proposal, then reach out via Slack or the mailing list with a +description of the problem statement. If one or more of the maintainers agrees that the problem statement is within the +scope of the project (see [SCOPE.md](SCOPE.md)) and is appropriate to be addressed by a proposal, then a maintainer will +be assigned as your proposal's sponsor. The sponsor can provide you with support during the drafting of the proposal, +including sharing additional project and roadmap context as it relates to your problem statement, answering questions, +giving feedback, etc. + +### Proposal Template + +The below template is an example `README.md` for a new proposal. Other than the high-level details at the top of the +template (title, authors, status, sponsor, and approval_date) +and the disclaimer at the top, please use whichever sections make the most sense for your proposal. + +```markdown +--- +title: "The Name of My Proposal" +authors: [ "@margocrawf", "@enj" ] +status: "draft" +sponsor: [ "@cfryanr" ] +approval_date: "" +--- + +*Disclaimer*: Proposals are point-in-time designs and decisions. +Once approved and implemented, they become historical documents. +If you are reading an old proposal, please be aware that the +features described herein might have continued to evolve since. + +# + +## Problem Statement +This is a short summary of the problem that exists, why it needs to be +solved: what specific needs are being met. Compelling problem statements +include concrete examples and use cases (even if only by reference). +How exactly the proposal would meet those needs should be located in the +"Proposal" section, not this one. The goal of this section is to help +readers quickly empathize with the target users' current experience to +motivate the proposed change. + +### How Pinniped Works Today (as of version vX.X.X) +How Pinniped works today in the context of the problem statement. +This will typically detail how Pinniped falls short of supporting +the desired use case(s). + +## Terminology / Concepts +Define any terms or concepts that are used throughout this proposal. + +## Proposal +The primary content of the proposal. Subsections will explain how the +problem(s) will be addressed. + +### Goals and Non-goals +A short list of what the goals of this proposal are and are not. + +### Specification / How it Solves the Use Cases +Detailed explanation of the proposal's design. This will typically +also detail how the specification supports the desired use cases. +If some use cases or parts of some use cases are being deferred +to a future proposal, that might be mentioned here as well. + +#### API Changes +Describe how Pinniped's API will change. APIs include CLI commands, +HTTP endpoints, aggregated API endpoints, CRDs, etc. +Detail changes to their inputs, outputs, and behavior. +What will the default values be for any new fields or parameters? + +#### Upgrades +Describe how upgrading to a new version of Pinniped which includes +these features would work. Are the new changes backwards compatible? +Can new and old versions of the CLI and servers be mixed? +Will it be possible to downgrade after upgrading? + +#### Tests +What kind of integration tests could be used to test the new features? + +#### New Dependencies +Would any significant new project dependencies be needed to support +the implementation? Consider Golang libraries, CI infrastructure, etc. + +#### Performance Considerations +Any concerns with scalability, performance, or reliability for the +implementation? + +#### Observability Considerations +Any new log statements or other considerations to make this feature +observable and debuggable for admin users? + +#### Security Considerations +How does the proposal consider security? What makes the new features +secure? + +#### Usability Considerations +How does the proposal consider usability for the end user (kubectl user) +and for the admin user who installs and configures Pinniped? + +#### Documentation Considerations +How will users discover the new features? Will docs changes be required +during implementation? + +### Other Approaches Considered +Mention of other reasonable ways that the problem(s) +could be addressed with rationale for why they were less +desirable than the proposed approach. + +## Open Questions +A list of questions that need to be answered. + +## Answered Questions +A list of questions that have been answered. + +## Implementation Plan +Who will implement this proposal once it is finished and approved? +Do you already have ideas for how you might approach the implementation +in an iterative fashion? For a large proposal with an iterative plan, +where might you draw the line to define a minimum viable version? + +## Implementation PRs +This section is a placeholder to list the PRs that implement this proposal. +This section should be left empty until after the proposal is approved. +After implementation, the proposal can be updated to list related +implementation PRs. +``` + +## Proposal States + +| Status | Definition | +| --- | --- | +| `draft` | The proposal is actively being written by the proposer. Not yet ready for review. | +| `in-review` | The proposal is being reviewed by the community and the project maintainers. | +| `accepted` | The proposal has been accepted by the project maintainers. | +| `rejected` | The proposal has been rejected by the project maintainers. | +| `implemented` | The proposal was accepted and has since been implemented. | + +## Lifecycle of a Proposal + +1. Author adds a proposal by creating a PR in draft mode. (Authors can save their work until ready.) +2. When the author elaborates the proposal sufficiently to withstand critique they: + 1. change the status to `in-review` and + 2. mark the PR as "Ready for Review". +3. The community critiques the proposal by adding PR reviews in order to mature/converge on the proposal. +4. When the maintainers reach consensus or supermajority to accept a proposal, they: + 1. change the status to `accepted`, + 2. adjust the proposal number in the subdirectory's name if needed, + 3. record both majority and dissenting opinions, + 4. merge the PR, thus adding the new proposal to the `main` branch, + 5. code implementation PRs are submitted separately to implement the solution. +5. During implementation of an accepted proposal: + 1. if it is discovered that significant unanticipated changes are needed to the proposal, then the implementation + work should be paused and the proposal should be updated with the new details to be reviewed by the maintainers + again before resuming implementation, and + 2. when all implementation PRs are merged, the proposal doc should be updated to have status `implemented` and to + list the related PRs. +6. When the maintainers do not reach consensus or supermajority, then the proposal is rejected, and they: + 1. may mark the status `rejected`, and + 2. close the PR with a note explaining the rejection. +7. Rejected proposal PRs may be reopened and moved back to `in-review` if there are material changes to the proposal + which address the reasons for rejection. + +## Proposal Review + +Once a proposal PR marked as "Ready for Review", the community and all project maintainers will review the proposal. The +goal of the review is to gain an understanding of the problem being solved and the design of the proposed solution. + +Maintainers will consider all aspects of the proposed problem and solution, including but not limited to: + +- Is the problem within scope for the project? +- Would the additional future cost of maintenance imposed by an implementation of the solution justify solving the + problem? +- Is the solution reasonably consistent with the rest of the project? +- How does the solution impact the usability, security, scalability, performance, observability, and reliability of + Pinniped? +- How might an implementation of the solution be architected and tested via automation? +- What risks might be introduced by an implementation of the solution? +- The opportunity cost of the time it would take to implement the solution, if the implementation is to be done by the + maintainers. + +## Maintenance of Accepted Proposal Documents + +Proposal documents reflect a point-in-time design and decision. Once approved, they become historical documents, not +living documents. There is no expectation that they will be maintained in the future. Instead, significant changes to a +feature which came from a previous proposal should be proposed as a fresh proposal. New proposals should link to +previous proposals for historical context when appropriate. + +## Getting Help with the Proposal Process + +Please reach out to the maintainers in the Kubernetes Slack Workspace within +the [#pinniped](https://kubernetes.slack.com/archives/C01BW364RJA) channel or on +the [Pinniped mailing list](mailto:project-pinniped@googlegroups.com) with any questions. From bc6827b2e1985afc8b2cdda264ccdadb56550478 Mon Sep 17 00:00:00 2001 From: Ryan Richard Date: Thu, 17 Feb 2022 10:08:37 -0800 Subject: [PATCH 07/10] Auto-format GOVERNANCE.md --- GOVERNANCE.md | 53 +++++++++++++++++++++++++++++++++++++++------------ 1 file changed, 41 insertions(+), 12 deletions(-) diff --git a/GOVERNANCE.md b/GOVERNANCE.md index 3a7b7fb45..6d8060223 100644 --- a/GOVERNANCE.md +++ b/GOVERNANCE.md @@ -1,39 +1,68 @@ # Pinniped Governance + This document defines the project governance for Pinniped. # Overview -**Pinniped** is committed to building an open, inclusive, productive and self-governing open source community focused on building authentication services for Kubernetes clusters. The -community is governed by this document which defines how all members should work together to achieve this goal. + +**Pinniped** is committed to building an open, inclusive, productive and self-governing open source community focused on +building authentication services for Kubernetes clusters. The community is governed by this document which defines how +all members should work together to achieve this goal. # Code of Conduct -The Pinniped community abides by this [code of conduct](https://github.com/vmware-tanzu/pinniped/blob/main/CODE_OF_CONDUCT.md). + +The Pinniped community abides by this +[code of conduct](https://github.com/vmware-tanzu/pinniped/blob/main/CODE_OF_CONDUCT.md). # Community Roles + * **Users:** Members that engage with the Pinniped community via any medium (Slack, GitHub, mailing lists, etc.). -* **Contributors:** Do regular contributions to the Pinniped project (documentation, code reviews, responding to issues, participating in proposal discussions, contributing code, etc.). -* **Maintainers:** Responsible for the overall health and direction of the project. They are the final reviewers of PRs and responsible for Pinniped releases. +* **Contributors:** Do regular contributions to the Pinniped project (documentation, code reviews, responding to issues, + participating in proposal discussions, contributing code, etc.). +* **Maintainers:** Responsible for the overall health and direction of the project. They are the final reviewers of PRs + and responsible for Pinniped releases. # Maintainers -New maintainers must be nominated by an existing maintainer and must be elected by a supermajority of existing maintainers. Likewise, maintainers can be removed by a supermajority of the existing maintainers or can resign by notifying one of the maintainers. -**Note:** If a maintainer leaves their employer they are still considered a maintainer of Pinniped, unless they voluntarily resign. Employment is not taken into consideration when determining maintainer eligibility unless the company itself violates our [Code of Conduct](https://github.com/vmware-tanzu/pinniped/blob/main/CODE_OF_CONDUCT.md). +New maintainers must be nominated by an existing maintainer and must be elected by a supermajority of existing +maintainers. Likewise, maintainers can be removed by a supermajority of the existing maintainers or can resign by +notifying one of the maintainers. + +**Note:** If a maintainer leaves their employer they are still considered a maintainer of Pinniped, unless they +voluntarily resign. Employment is not taken into consideration when determining maintainer eligibility unless the +company itself violates our [Code of Conduct](https://github.com/vmware-tanzu/pinniped/blob/main/CODE_OF_CONDUCT.md). # Decision Making -Ideally, all project decisions are resolved by consensus. If impossible, any maintainer may call a vote. Unless otherwise specified in this document, any vote will be decided by a supermajority of maintainers. + +Ideally, all project decisions are resolved by consensus. If impossible, any maintainer may call a vote. Unless +otherwise specified in this document, any vote will be decided by a supermajority of maintainers. ## Supermajority -A supermajority is defined as two-thirds of members in the group. A supermajority of maintainers is required for certain decisions as outlined in this document. A supermajority vote is equivalent to the number of votes in favor being at least twice the number of votes against. A vote to abstain equals not voting at all. For example, if you have 5 maintainers who all cast non-abstaining votes, then a supermajority vote is at least 4 votes in favor. Voting on decisions can happen on the mailing list, GitHub, Slack, email, or via a voting service, when appropriate. Maintainers can either vote "agree, yes, +1", "disagree, no, -1", or "abstain". A vote passes when supermajority is met. + +A supermajority is defined as two-thirds of members in the group. A supermajority of maintainers is required for certain +decisions as outlined in this document. A supermajority vote is equivalent to the number of votes in favor being at +least twice the number of votes against. A vote to abstain equals not voting at all. For example, if you have 5 +maintainers who all cast non-abstaining votes, then a supermajority vote is at least 4 votes in favor. Voting on +decisions can happen on the mailing list, GitHub, Slack, email, or via a voting service, when appropriate. Maintainers +can either vote "agree, yes, +1", "disagree, no, -1", or "abstain". A vote passes when supermajority is met. ## Lazy Consensus -To maintain velocity in Pinniped, the concept of [Lazy Consensus](http://en.osswiki.info/concepts/lazy_consensus) is practiced. -Other maintainers may chime in and request additional time for review, but should remain cognizant of blocking progress and abstain from delaying progress unless absolutely needed. The expectation is that blocking progress is accompanied by a guarantee to review and respond to the relevant action in short order. +To maintain velocity in Pinniped, the concept of [Lazy Consensus](http://en.osswiki.info/concepts/lazy_consensus) is +practiced. + +Other maintainers may chime in and request additional time for review, but should remain cognizant of blocking progress +and abstain from delaying progress unless absolutely needed. The expectation is that blocking progress is accompanied by +a guarantee to review and respond to the relevant action in short order. Lazy consensus does not apply to the process of: + * Removal of maintainers from Pinniped ## Updating Governance -All substantive changes in Governance, including substantive changes to the proposal process, require a supermajority agreement by all maintainers. + +All substantive changes in Governance, including substantive changes to the proposal process, require a supermajority +agreement by all maintainers. # Proposal Process + The proposal process is defined in [proposals/README.md](proposals/README.md). From 60cc61cdaa722303d9fbc75b38ce361450e170ec Mon Sep 17 00:00:00 2001 From: Ryan Richard Date: Thu, 17 Feb 2022 10:42:10 -0800 Subject: [PATCH 08/10] Add the concept of a tracking issue to the proposal process --- ...feature-proposal.md => feature_request.md} | 6 +++- .github/ISSUE_TEMPLATE/proposal_tracking.md | 34 +++++++++++++++++++ proposals/README.md | 34 ++++++++++++------- 3 files changed, 60 insertions(+), 14 deletions(-) rename .github/ISSUE_TEMPLATE/{feature-proposal.md => feature_request.md} (97%) create mode 100644 .github/ISSUE_TEMPLATE/proposal_tracking.md diff --git a/.github/ISSUE_TEMPLATE/feature-proposal.md b/.github/ISSUE_TEMPLATE/feature_request.md similarity index 97% rename from .github/ISSUE_TEMPLATE/feature-proposal.md rename to .github/ISSUE_TEMPLATE/feature_request.md index fdb280164..bf7d309c9 100644 --- a/.github/ISSUE_TEMPLATE/feature-proposal.md +++ b/.github/ISSUE_TEMPLATE/feature_request.md @@ -1,5 +1,5 @@ --- -name: Feature proposal +name: Feature request about: Suggest a way to improve this project title: '' labels: '' @@ -16,12 +16,15 @@ It is recommended that you include screenshots and logs to help everyone achieve --> **Is your feature request related to a problem? Please describe.** + A clear and concise description of what the problem is. Ex. I'm always frustrated when [...] **Describe the solution you'd like** + A clear and concise description of what you want to happen. **Describe alternatives you've considered** + A clear and concise description of any alternative solutions or features you've considered. **Are you considering submitting a PR for this feature?** @@ -32,4 +35,5 @@ A clear and concise description of any alternative solutions or features you've - **How will this feature be documented?** **Additional context** + Add any other context or screenshots about the feature request here. diff --git a/.github/ISSUE_TEMPLATE/proposal_tracking.md b/.github/ISSUE_TEMPLATE/proposal_tracking.md new file mode 100644 index 000000000..36444b600 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/proposal_tracking.md @@ -0,0 +1,34 @@ +--- +name: Proposal tracking +about: A tracking issue for a proposal document +title: '[Proposal] Your proposal title' +labels: 'proposal-tracking' +assignees: '' + +--- + + + +### Proposal Tracking Issue + +- Proposal: + +- Discussion Links: + - + - + +- Pull requests: + - + - diff --git a/proposals/README.md b/proposals/README.md index cd7571d7f..346339751 100644 --- a/proposals/README.md +++ b/proposals/README.md @@ -27,8 +27,12 @@ standard GitHub issue instead of using the proposal process. ## How to Submit a Proposal +Before submitting a proposal, please create a tracking issue. Open a new GitHub issue in this repo and choose the +"Proposal tracking" issue template. After creating the issue, note the issue's number. This tracking PR can be used +as a place for conversations beyond/between the proposal PR and implementation PRs. + To create a proposal, submit a PR to this repo introducing a new subdirectory under the `proposals` directory with a -terse name (for example, `0001_my-feature-name/`) prefixed by a monotonically incrementing proposal number. In that new +terse name (for example, `0001_my-feature-name/`) prefixed by the tracking issue's number. In that new subdirectory, create a `README.md` containing the core proposal. Include other files as necessary to help support understanding of the feature. @@ -173,28 +177,32 @@ implementation PRs. ## Lifecycle of a Proposal -1. Author adds a proposal by creating a PR in draft mode. (Authors can save their work until ready.) -2. When the author elaborates the proposal sufficiently to withstand critique they: +1. Author creates a tracking issue. +2. Author adds a proposal by creating a PR in draft mode. (Authors can save their work until ready.) +3. Author updates the tracking issue to have a link to the PR. +4. When the author elaborates the proposal sufficiently to withstand critique they: 1. change the status to `in-review` and 2. mark the PR as "Ready for Review". -3. The community critiques the proposal by adding PR reviews in order to mature/converge on the proposal. -4. When the maintainers reach consensus or supermajority to accept a proposal, they: +5. The community critiques the proposal by adding PR reviews in order to mature/converge on the proposal. +6. When the maintainers reach consensus or supermajority to accept a proposal, they: 1. change the status to `accepted`, 2. adjust the proposal number in the subdirectory's name if needed, 3. record both majority and dissenting opinions, 4. merge the PR, thus adding the new proposal to the `main` branch, 5. code implementation PRs are submitted separately to implement the solution. -5. During implementation of an accepted proposal: +7. During implementation of an accepted proposal: 1. if it is discovered that significant unanticipated changes are needed to the proposal, then the implementation work should be paused and the proposal should be updated with the new details to be reviewed by the maintainers - again before resuming implementation, and - 2. when all implementation PRs are merged, the proposal doc should be updated to have status `implemented` and to - list the related PRs. -6. When the maintainers do not reach consensus or supermajority, then the proposal is rejected, and they: + again before resuming implementation, + 2. as each implementation PR is created, the tracking issue should be updated to link to the new implantation PR, and + 3. when all implementation PRs are merged, the proposal doc should be updated to have status `implemented` and to + list the related PRs, and the tracking issue should be closed. +8. When the maintainers do not reach consensus or supermajority, then the proposal is rejected, and they: 1. may mark the status `rejected`, and - 2. close the PR with a note explaining the rejection. -7. Rejected proposal PRs may be reopened and moved back to `in-review` if there are material changes to the proposal - which address the reasons for rejection. + 2. close the PR with a note explaining the rejection, and + 3. close the related tracking issue. +9. Rejected proposal PRs (and the corresponding tracking issue) may be reopened and moved back to `in-review` if + there are material changes to the proposal which address the reasons for rejection. ## Proposal Review From 2f7713889a8082a6e361f6274601785f61494dd0 Mon Sep 17 00:00:00 2001 From: Ryan Richard Date: Thu, 17 Feb 2022 10:56:13 -0800 Subject: [PATCH 09/10] Remove an unnecessary step from the proposal lifecycle --- proposals/README.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/proposals/README.md b/proposals/README.md index 346339751..2208774f5 100644 --- a/proposals/README.md +++ b/proposals/README.md @@ -186,10 +186,9 @@ implementation PRs. 5. The community critiques the proposal by adding PR reviews in order to mature/converge on the proposal. 6. When the maintainers reach consensus or supermajority to accept a proposal, they: 1. change the status to `accepted`, - 2. adjust the proposal number in the subdirectory's name if needed, - 3. record both majority and dissenting opinions, - 4. merge the PR, thus adding the new proposal to the `main` branch, - 5. code implementation PRs are submitted separately to implement the solution. + 2. record both majority and dissenting opinions, + 3. merge the PR, thus adding the new proposal to the `main` branch, + 4. code implementation PRs are submitted separately to implement the solution. 7. During implementation of an accepted proposal: 1. if it is discovered that significant unanticipated changes are needed to the proposal, then the implementation work should be paused and the proposal should be updated with the new details to be reviewed by the maintainers From 9526009f7491b0145854f6990f9444db5020d663 Mon Sep 17 00:00:00 2001 From: Ryan Richard Date: Thu, 17 Feb 2022 10:59:23 -0800 Subject: [PATCH 10/10] Fix spelling typo in proposals/README.md Co-authored-by: Mo Khan --- proposals/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/README.md b/proposals/README.md index 2208774f5..706961ccc 100644 --- a/proposals/README.md +++ b/proposals/README.md @@ -193,7 +193,7 @@ implementation PRs. 1. if it is discovered that significant unanticipated changes are needed to the proposal, then the implementation work should be paused and the proposal should be updated with the new details to be reviewed by the maintainers again before resuming implementation, - 2. as each implementation PR is created, the tracking issue should be updated to link to the new implantation PR, and + 2. as each implementation PR is created, the tracking issue should be updated to link to the new implementation PR, and 3. when all implementation PRs are merged, the proposal doc should be updated to have status `implemented` and to list the related PRs, and the tracking issue should be closed. 8. When the maintainers do not reach consensus or supermajority, then the proposal is rejected, and they: