From de9184a1cdd43823847e8c4218dc893e44dc9778 Mon Sep 17 00:00:00 2001 From: Emily Casey Date: Wed, 11 May 2022 08:16:00 -0400 Subject: [PATCH 01/10] New RFC Process Signed-off-by: Emily Casey --- text/0000-rfc-process.md | 162 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 162 insertions(+) create mode 100644 text/0000-rfc-process.md diff --git a/text/0000-rfc-process.md b/text/0000-rfc-process.md new file mode 100644 index 000000000..fad9f4a8b --- /dev/null +++ b/text/0000-rfc-process.md @@ -0,0 +1,162 @@ +# Meta +[meta]: #meta +- Name: RFC Process +- Start Date: 2021-05-10 +- Author(s): [@ekcasey](https://github.com/ekcasey) +- Status: Draft +- RFC Pull Request: (leave blank) +- CNB Pull Request: (leave blank) +- CNB Issue: (leave blank) +- Supersedes: [RFC 0004](0004-rfc-process.md) + +# Summary +[summary]: #summary + +The "RFC" (request for comments) process provide a consistent and controlled path for new features and other substantive changes to enter the project. + +The RFC process: +* provides a set of checkpoints that ensure changes align with the overall technical and strategic vision for the process. +* ensures the motivation for a change is clear. +* ensures the impact of a change on users is clear and migration path and backwards compatibility are considered. +* aligns stakeholders on any changes to the user interface(s) and/or APIs (e.g. pack user interface, platform API, buildpack API). +* aligns stakeholders on any substantive architectural decision changes +* Aligns stakeholders on any processes or workflows adopted by the project. +* provides visibility to the community regarding on-going work and upcoming changes. +* provides a mechanism by which any interested party can provide early feedback on an upcoming change. +* is open to anyone! We enthusiastically welcome RFCs from authors that have no formal role in project governance (yet ;p). + +The RFC process **is not**: +* A replacement for high-quality user-facing documentation. +* A transaction log of changes. Readers should be able to understand the change proposed without undue reference to previous RFCs. +* A feature request process. RFCs require a level of design and implementation detail that goes beyond a feature request. Pure feature requests should instead be initiated as discussions on the community repo, issues on this repo, or issues on component repos. These requests may serve as the motivation for future RFCs. + + +# Definitions +[definitions]: #definitions + +**Technical Oversight Committee**: The governing body responsible for overseeing the project as described in our governance document. + +**Team**: A group responsible for a particular area of the project. + +**Team Lead**: A team maintainer with special responsibilities for representing the concerns of a team to the project, including casting binding votes on project RFCs. + +**RFC**: A document proposing a substantive change to the project as described in this document. + +**Project RFC**: An RFC with cross-cutting implications, requiring collaboration between multiple teams or affecting multiple personas. + +**Team RFC**: An RFC with narrower implication in comparison to a project RFC, with work scoped to a single team and implications for a narrower set of personas. + +**Call for Votes**: When an RFC is deemed ready by a team lead, that team lead initiates the voting process with a call for votes. At this point the RFC is closed to modification. + +**End Date**: When a call for votes is initiated, an end date for voting is set. Any person wishing to vote on an RFC must do so by the end date. + +**Lazy Consensus**: Voting on project level RFCs is done by lazy consensus. Any project member with a binding vote who has not voted by the end date is assumed to assent to the RFC. + +**Binding Vote**: Binding Votes have formal power within the RFC process. A single no vote by a project member with a binding vote is sufficient to reject an RFC. + +**Non-Binding Vote**: Anyone from the project or community may cast a non-binding vote on an RFC to express their position. While these votes do not have formal power they are taken seriously and may affect the votes of members with binding votes. + + +# Motivation +[motivation]: #motivation + +This RFC process is an evolution of our [previous process](0004-rfc-process.md). In comparison to the previous process this proposal makes two substantive cha + +# What it is +[what-it-is]: #what-it-is + +### What Types of Changes Require an RFC? + +#### Project vs Team RFCs + +### Process + +#### Drafting +All RFCs begin life as a draft. Anyone wishing to propose a change to the project should create a draft RFC by: + +- Fork the RFC repo: +- Copy `0000-template.md` to `text/0000-my-feature.md` (where 'my-feature' is descriptive. don't assign an RFC number yet). +- Fill in RFC. Any section can be marked as "N/A" if not applicable. +- Submit a pull request. + +#### Finding a Steward +All RFCs, even project RFCs "belong" to a team. The team lead of the responsible team is the steward of the RFC. The author and the steward of an RFC may, at times, be the same person. + +In many but not all cases the appropriate team to steward an RFC will be obvious. When the appropriate steward is not obvious the author should work with the community to find a home within one of the teams. Factors to consider when finding home include: +* Which team has the most relevant technical context? +* Which team has the deepest understanding of the use-case and the needs of impacted personas? +* Which team is responsible for the components most impacted by the proposed change? +* Which team is enthusiastic about supporting the change? + +If a home cannot be found for a draft RFC it remains in draft until one can be found. This does not necessary mean that the RFC is not a good idea or not something the project will take up eventually. It may simply be that the project does not have the bandwidth to prioritize this particular time. + +#### Stewardship + +The steward and their team should: + * work with the author of the RFC to ensure that the RFC is complete and implementable contingent upon approval. This can happen synchronously at team working groups or asynchronously via github and slack. + * raise visibility to and solicit feedback from other stakeholders including the TOC, other teams, and the community at large. This can happen synchronously at the project working group and asynchronously vai github and slack. + * drive consensus for the RFC by incorporating feedback from stakeholders so that the RFC has the best possible chance of approval during the voting process. + * ensure there is a plan in place to implement the RFC in a reasonable time frame, contingent upon approval. The team itself need not implement the RFC but we should not approve RFC for which we have no concrete plan to implement. + * in the case of complicated or risky RFCs, a POC should be developed at this stage to validate and de-risk the proposed design. + +#### Voting + +Ideally the voting should be a formality and not a moment to discover new disagreement, consensus already haven been driven by the steward. + +When the steward deems the RFC ready and likely to be accepted they should formally call for votes and set an end date for voting. This process does not prescribe a length for the voting window, but stewards should make a good faith effort to ensure that all interested parties, and in particular those with binding votes, have adequate opportunity to read and cast votes. + +For project RFCs, all TOC members and all team leads are given a binding vote. + +For team RFCs, all team maintainers are given a binding vote. + +Votes are cast via reviews on the RFC PR. Accepting the PR is interpreted as a yes vote while a request for changes is interpreted as a no vote. + +##### Acceptance + +If the end date of the vote arrives without a no vote from a member with binding vote, the RFC is accepted. It will be merged into the repo and assigned a number. Implementation can begin. + +##### Rejection + +If a single no vote is cast before the arrival of the end date the RFC is immediately rejected. The same RFC may be brought to a vote again in the future assuming the concerns that lead to the no vote are addressed. + +# How it Works +[how-it-works]: #how-it-works + +### Amending the RFC Process + +The RFC process should be amended through the RFC process. However, the TOC reserves the right to change the process via a super-majority vote in the unlikely even that the process prove so irreparably flawed as to preclude its amendment via the process. + +# Migration +[migration]: #migration + +This RFC should be accepted via the existing RFC process. The new process will take effect immediately after its ratification, superseding in its entirety the previous process. + +# Drawbacks +[drawbacks]: #drawbacks + +Why should we *not* do this? + +# Alternatives +[alternatives]: #alternatives + +- What other designs have been considered? +- Why is this proposal the best? +- What is the impact of not doing this? + +# Prior Art +[prior-art]: #prior-art + +Discuss prior art, both the good and bad. + +# Unresolved Questions +[unresolved-questions]: #unresolved-questions + +- What parts of the design do you expect to be resolved before this gets merged? +- What parts of the design do you expect to be resolved through implementation of the feature? +- What related issues do you consider out of scope for this RFC that could be addressed in the future independently of the solution that comes out of this RFC? + +# Spec. Changes (OPTIONAL) +[spec-changes]: #spec-changes +Does this RFC entail any proposed changes to the core specifications or extensions? If so, please document changes here. +Examples of a spec. change might be new lifecycle flags, new `buildpack.toml` fields, new fields in the buildpackage label, etc. +This section is not intended to be binding, but as discussion of an RFC unfolds, if spec changes are necessary, they should be documented here. From 0999ea7b6f0414bf9bac2ca1bcebf48a797020a8 Mon Sep 17 00:00:00 2001 From: Emily Casey Date: Wed, 11 May 2022 18:09:43 -0400 Subject: [PATCH 02/10] Adds process details * Additional terminology around voting * Adds more details to the process section * What requires an RFC * Project vs Team RFCs Signed-off-by: Emily Casey --- text/0000-rfc-process.md | 96 ++++++++++++++++++++++++++++++---------- 1 file changed, 72 insertions(+), 24 deletions(-) diff --git a/text/0000-rfc-process.md b/text/0000-rfc-process.md index fad9f4a8b..67c78d606 100644 --- a/text/0000-rfc-process.md +++ b/text/0000-rfc-process.md @@ -19,16 +19,17 @@ The RFC process: * ensures the motivation for a change is clear. * ensures the impact of a change on users is clear and migration path and backwards compatibility are considered. * aligns stakeholders on any changes to the user interface(s) and/or APIs (e.g. pack user interface, platform API, buildpack API). -* aligns stakeholders on any substantive architectural decision changes -* Aligns stakeholders on any processes or workflows adopted by the project. -* provides visibility to the community regarding on-going work and upcoming changes. +* aligns stakeholders on any substantive architectural changes. +* aligns stakeholders on any processes or workflows adopted by the project. +* provides visibility to the community regarding ongoing work and upcoming changes. * provides a mechanism by which any interested party can provide early feedback on an upcoming change. +* provides a version controlled record of our decisions and the thought-process behind them. * is open to anyone! We enthusiastically welcome RFCs from authors that have no formal role in project governance (yet ;p). The RFC process **is not**: -* A replacement for high-quality user-facing documentation. -* A transaction log of changes. Readers should be able to understand the change proposed without undue reference to previous RFCs. -* A feature request process. RFCs require a level of design and implementation detail that goes beyond a feature request. Pure feature requests should instead be initiated as discussions on the community repo, issues on this repo, or issues on component repos. These requests may serve as the motivation for future RFCs. +* a replacement for high-quality user-facing documentation(although high-quality RFCs enable the creation of high-quality documentation). +* a transaction log of changes. Readers should be able to understand the change proposed without undue reference to previous RFCs. +* a feature request process. RFCs require a level of design and implementation detail that goes beyond a feature request. Pure feature requests should instead be initiated as discussions on the community repo, issues on this repo, or issues on component repos. These requests may serve as the motivation for future RFCs. # Definitions @@ -44,12 +45,18 @@ The RFC process **is not**: **Project RFC**: An RFC with cross-cutting implications, requiring collaboration between multiple teams or affecting multiple personas. -**Team RFC**: An RFC with narrower implication in comparison to a project RFC, with work scoped to a single team and implications for a narrower set of personas. +**Team RFC**: An RFC with narrower implication in comparison to a project RFC, with work scoped to a single team and implications for a narrower set of personas. + +**Author**: The author or authors of an RFC are responsible for producing the draft RFC and updating it to incorporate feedback. Changes should not be made to a draft RFC without the author's consent. + +**Steward**: The steward of an RFC is responsible for shepherding an RFC through the process, including working with the author to ensure RFC completeness and quality, and building consensus among stakeholders. **Call for Votes**: When an RFC is deemed ready by a team lead, that team lead initiates the voting process with a call for votes. At this point the RFC is closed to modification. **End Date**: When a call for votes is initiated, an end date for voting is set. Any person wishing to vote on an RFC must do so by the end date. +**Voting Window**: The time period between a call for votes and the voting end date is referred to as the voting window. + **Lazy Consensus**: Voting on project level RFCs is done by lazy consensus. Any project member with a binding vote who has not voted by the end date is assumed to assent to the RFC. **Binding Vote**: Binding Votes have formal power within the RFC process. A single no vote by a project member with a binding vote is sufficient to reject an RFC. @@ -60,15 +67,41 @@ The RFC process **is not**: # Motivation [motivation]: #motivation -This RFC process is an evolution of our [previous process](0004-rfc-process.md). In comparison to the previous process this proposal makes two substantive cha +This RFC process is an evolution of our [previous process](0004-rfc-process.md). + +TODO # What it is [what-it-is]: #what-it-is ### What Types of Changes Require an RFC? +Any "substantive" change to the project requires an RFC. substantive includes but is not limited to: +* changes to the specification. +* the adoption, creation, or deprecation of a component (e.g. a new platform implementation, a new shared library, a new system buildpack). +* new features (e.g. a new pack command, a new flag on an existing pack command, an addition to the buildpack API) +* any major refactor that affects consumers of our libraries or materially impacts contribution. +* any major re-architecture especially if it has noteworthy implications for security or performance. +* introduction of new processes or changes to our existing processes including the RFC process. + +If there is any doubt, maintainers should prefer opening an "unecessary" RFC to surprising users was unexpectedly impactful changes. + #### Project vs Team RFCs +An RFC should be a project RFC if: +* it impacts the spec. +* it introduces a new component. +* its implementation necessitates coordination across multiple team. +* it meaningfully impacts multiple personas (e.g. buildpack authors and platform authors). +* the TOC requests that it be a project RFC. + +Given the nature of our project many RFCs will happen at the project level. However, some types of changes are more appropriately scoped to the team level. Some examples include: +* Platform example: additions to or modification of the pack CLI interface (e.g. [pack pull policy](0046-pack-pull-policy.md)) or library interface (e.g. [pack logging refactor](0002-pack-logging-refactor.md)), provided these changes do not require changes to components external to the platform team. +* BAT example: a new major version of the libcnb API. +* Implementation example: [Layer history](0102-history.md) or the lifecycle [multicall binary](0024-lifecycle-multicall-binary-for-build.md). +* Distribution example: [Update CNB Registry JSON Schema](https://github.com/buildpacks/rfcs/pull/45). +* Learning example: [intro video](0090-intro-video-script.md). + ### Process #### Drafting @@ -80,44 +113,56 @@ All RFCs begin life as a draft. Anyone wishing to propose a change to the projec - Submit a pull request. #### Finding a Steward -All RFCs, even project RFCs "belong" to a team. The team lead of the responsible team is the steward of the RFC. The author and the steward of an RFC may, at times, be the same person. +All RFCs, even project RFCs "belong" to a team. For project RFCs, The team lead of the responsible team is the steward of the RFC. For team RFCs any maintainer may be the steward. The author and the steward of an RFC may, at times, be the same person. -In many but not all cases the appropriate team to steward an RFC will be obvious. When the appropriate steward is not obvious the author should work with the community to find a home within one of the teams. Factors to consider when finding home include: +In many but not all cases the appropriate team to own an RFC will be obvious. When the appropriate team is not obvious, the author should work with the community to find a home within one of the teams. Factors to consider when finding home include: * Which team has the most relevant technical context? * Which team has the deepest understanding of the use-case and the needs of impacted personas? * Which team is responsible for the components most impacted by the proposed change? * Which team is enthusiastic about supporting the change? -If a home cannot be found for a draft RFC it remains in draft until one can be found. This does not necessary mean that the RFC is not a good idea or not something the project will take up eventually. It may simply be that the project does not have the bandwidth to prioritize this particular time. +If a home cannot be found for a draft RFC it remains in draft until one can be found. This does not necessary mean that the RFC is not a good idea or isn't something the project will take up eventually. It may simply be that the project does not have the bandwidth to prioritize this particular change at this particular time. #### Stewardship The steward and their team should: * work with the author of the RFC to ensure that the RFC is complete and implementable contingent upon approval. This can happen synchronously at team working groups or asynchronously via github and slack. - * raise visibility to and solicit feedback from other stakeholders including the TOC, other teams, and the community at large. This can happen synchronously at the project working group and asynchronously vai github and slack. + * raise visibility to and solicit feedback from other stakeholders including the TOC, other teams, and the community at large. This can happen synchronously at the project working group and asynchronously via github and slack. * drive consensus for the RFC by incorporating feedback from stakeholders so that the RFC has the best possible chance of approval during the voting process. - * ensure there is a plan in place to implement the RFC in a reasonable time frame, contingent upon approval. The team itself need not implement the RFC but we should not approve RFC for which we have no concrete plan to implement. + * ensure there is a plan in place to implement the RFC in a reasonable time frame, contingent upon approval. The team itself need not implement the RFC but we should not approve RFCs for which we have no concrete plan to implement. * in the case of complicated or risky RFCs, a POC should be developed at this stage to validate and de-risk the proposed design. #### Voting Ideally the voting should be a formality and not a moment to discover new disagreement, consensus already haven been driven by the steward. -When the steward deems the RFC ready and likely to be accepted they should formally call for votes and set an end date for voting. This process does not prescribe a length for the voting window, but stewards should make a good faith effort to ensure that all interested parties, and in particular those with binding votes, have adequate opportunity to read and cast votes. +When the steward deems the RFC ready and likely to be accepted they should formally call for votes and set an end date for voting. This process does not prescribe a length for the voting window, but stewards should make a good faith effort to ensure that all interested parties, and in particular those with binding votes, have adequate opportunity to review the finalized RFC and cast votes. + +The RFC may not be edited during the voting window. For project RFCs, all TOC members and all team leads are given a binding vote. For team RFCs, all team maintainers are given a binding vote. -Votes are cast via reviews on the RFC PR. Accepting the PR is interpreted as a yes vote while a request for changes is interpreted as a no vote. +Votes are cast via reviews on the RFC PR. Accepting the PR signifies a yes vote while a request for changes signifies a no vote. If all members with a binding vote vote in the affirmative, the voting window may close early. ##### Acceptance -If the end date of the vote arrives without a no vote from a member with binding vote, the RFC is accepted. It will be merged into the repo and assigned a number. Implementation can begin. +If the end date of the vote arrives without a no vote from a member with binding vote, the RFC is accepted. It will be merged into the repo and assigned a number. The steward should create a tracking issue to coordinate implementation and link the tracking issue in the RFC header. When this is complete, implementation can begin. ##### Rejection -If a single no vote is cast before the arrival of the end date the RFC is immediately rejected. The same RFC may be brought to a vote again in the future assuming the concerns that lead to the no vote are addressed. +If a single no vote is cast before the arrival of the end date the RFC is immediately rejected and the PR should be closed. + +The same RFC may be re-opened and brought to a vote again in the future assuming the concerns that lead to the no vote are addressed. + +### Amending an RFC + +TODO + +### Amending the RFC Process + +The RFC process should be amended through the RFC process. However, the TOC reserves the right to change the process via a super-majority vote in the unlikely even that the process prove so irreparably flawed as to preclude its amendment via the process. # How it Works [how-it-works]: #how-it-works @@ -136,6 +181,8 @@ This RFC should be accepted via the existing RFC process. The new process will t Why should we *not* do this? +TODO + # Alternatives [alternatives]: #alternatives @@ -143,20 +190,21 @@ Why should we *not* do this? - Why is this proposal the best? - What is the impact of not doing this? +TODO + # Prior Art [prior-art]: #prior-art -Discuss prior art, both the good and bad. +TODO + +* Borrows heavily from TEP and KEP processes # Unresolved Questions [unresolved-questions]: #unresolved-questions -- What parts of the design do you expect to be resolved before this gets merged? -- What parts of the design do you expect to be resolved through implementation of the feature? -- What related issues do you consider out of scope for this RFC that could be addressed in the future independently of the solution that comes out of this RFC? +TODO # Spec. Changes (OPTIONAL) [spec-changes]: #spec-changes -Does this RFC entail any proposed changes to the core specifications or extensions? If so, please document changes here. -Examples of a spec. change might be new lifecycle flags, new `buildpack.toml` fields, new fields in the buildpackage label, etc. -This section is not intended to be binding, but as discussion of an RFC unfolds, if spec changes are necessary, they should be documented here. + +N/A From 266bfb01ce288954d59489a89ef43767371f9e30 Mon Sep 17 00:00:00 2001 From: Emily Casey Date: Wed, 20 Jul 2022 16:49:27 -0400 Subject: [PATCH 03/10] Fill in motivation section Signed-off-by: Emily Casey --- text/0000-rfc-process.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/text/0000-rfc-process.md b/text/0000-rfc-process.md index 67c78d606..a53bd2334 100644 --- a/text/0000-rfc-process.md +++ b/text/0000-rfc-process.md @@ -69,7 +69,11 @@ The RFC process **is not**: This RFC process is an evolution of our [previous process](0004-rfc-process.md). -TODO +As the project grows our process needs to grow with it. Compared to the previous iteration, this new process should: +1. **Re-balance responsibilities**. We wish to empower team leads to take ownership of the future of the project and transition the TOC into an oversight role. +2. **Favor action**. By moving from a super-majority vote to a lazy-consensus we remove the ability to block change through inaction. It is now the responsibility of those with concerns to raise them in a timely fashion. +3. **Manage our bandwidth**. Sometimes we need to say "not now" to a good idea to manage the number of large changes proceeding simultaneously. This new process should help the project focus on shipping high-quality enhancements by managing the number of in-flight RFCs, and ensuring each approved RFC has an implementer. +4. **Improve Readability**. By allowing amendments to RFCs we make life easier for anyone wishing to understand a change by ensuring they can find the full plan in a single document. # What it is [what-it-is]: #what-it-is From 7bf9865c33df1036625cb2a9127282d62eb5ade3 Mon Sep 17 00:00:00 2001 From: Emily Casey Date: Wed, 20 Jul 2022 16:50:07 -0400 Subject: [PATCH 04/10] minor fixes --- text/0000-rfc-process.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/text/0000-rfc-process.md b/text/0000-rfc-process.md index a53bd2334..091449228 100644 --- a/text/0000-rfc-process.md +++ b/text/0000-rfc-process.md @@ -95,12 +95,12 @@ If there is any doubt, maintainers should prefer opening an "unecessary" RFC to An RFC should be a project RFC if: * it impacts the spec. * it introduces a new component. -* its implementation necessitates coordination across multiple team. +* its implementation necessitates coordination across multiple teams. * it meaningfully impacts multiple personas (e.g. buildpack authors and platform authors). * the TOC requests that it be a project RFC. Given the nature of our project many RFCs will happen at the project level. However, some types of changes are more appropriately scoped to the team level. Some examples include: -* Platform example: additions to or modification of the pack CLI interface (e.g. [pack pull policy](0046-pack-pull-policy.md)) or library interface (e.g. [pack logging refactor](0002-pack-logging-refactor.md)), provided these changes do not require changes to components external to the platform team. +* Platform example: additions to or modification of the pack CLI interface (e.g. [pack pull policy](0046-pack-pull-policy.md)) or library interface (e.g. [pack logging refactor](0002-pack-logging-refactor.md)). * BAT example: a new major version of the libcnb API. * Implementation example: [Layer history](0102-history.md) or the lifecycle [multicall binary](0024-lifecycle-multicall-binary-for-build.md). * Distribution example: [Update CNB Registry JSON Schema](https://github.com/buildpacks/rfcs/pull/45). From 9bd4f396adaa60ad1c02ea46729953f74cd69509 Mon Sep 17 00:00:00 2001 From: Emily Casey Date: Wed, 20 Jul 2022 16:51:58 -0400 Subject: [PATCH 05/10] Adds Requesting an RFC seciton to Process Signed-off-by: Emily Casey --- text/0000-rfc-process.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/text/0000-rfc-process.md b/text/0000-rfc-process.md index 091449228..5ab6f7ece 100644 --- a/text/0000-rfc-process.md +++ b/text/0000-rfc-process.md @@ -108,7 +108,10 @@ Given the nature of our project many RFCs will happen at the project level. Howe ### Process -#### Drafting +#### Requesting an RFC +If you believe an RFC should be written but are either not prepared to author it personally or not prepared to do it _now_, please open an issue on this repo with a high level description of the desired change. This helps us keep track of good ideas and match make ambitious contributors with appropriately sized challenges. + +#### Drafting an RFC All RFCs begin life as a draft. Anyone wishing to propose a change to the project should create a draft RFC by: - Fork the RFC repo: From a31c7051e24b21e5ef3a45a97209f266508ebae2 Mon Sep 17 00:00:00 2001 From: Emily Casey Date: Thu, 28 Jul 2022 09:42:18 -0400 Subject: [PATCH 06/10] Adds ammendment mechanism Signed-off-by: Emily Casey --- 0000-template.md | 21 +++++++++++++++++++++ text/0000-rfc-process.md | 8 +++++++- 2 files changed, 28 insertions(+), 1 deletion(-) diff --git a/0000-template.md b/0000-template.md index b4256f4e7..cc5d06dc3 100644 --- a/0000-template.md +++ b/0000-template.md @@ -78,3 +78,24 @@ Discuss prior art, both the good and bad. Does this RFC entail any proposed changes to the core specifications or extensions? If so, please document changes here. Examples of a spec. change might be new lifecycle flags, new `buildpack.toml` fields, new fields in the buildpackage label, etc. This section is not intended to be binding, but as discussion of an RFC unfolds, if spec changes are necessary, they should be documented here. + +# History +[history]: #history + + \ No newline at end of file diff --git a/text/0000-rfc-process.md b/text/0000-rfc-process.md index 5ab6f7ece..02fcc011f 100644 --- a/text/0000-rfc-process.md +++ b/text/0000-rfc-process.md @@ -165,7 +165,13 @@ The same RFC may be re-opened and brought to a vote again in the future assuming ### Amending an RFC -TODO +While we should strive to get the details right the first time, by doing our due diligence including a proof of concept implementation for larger/riskier RFCs, there will be times when we discover during the process of implementation that something about the original plan was incomplete or needs adjustment. Small changes may be PR'ed by the implementer and merged upon approval by the steward. It is the responsibility of the Steward to determine what changes are minor enough to qualify as an amendment and which are fundamental and/or controversial enough to require a new superseding RFC. + +PRs that amend an RFC should add an amendment to the [History](../0000-template.md#history) section of the RFC document with: +1. Amendment Metadata +2. A summary of the changes +3. The motivation for the changes + ### Amending the RFC Process From 9afb723934c5b5a767ebe430ac51307123f1ffc9 Mon Sep 17 00:00:00 2001 From: Emily Casey Date: Thu, 28 Jul 2022 09:55:10 -0400 Subject: [PATCH 07/10] Documents Labels Signed-off-by: Emily Casey --- text/0000-rfc-process.md | 23 +++++++++++++++++++---- 1 file changed, 19 insertions(+), 4 deletions(-) diff --git a/text/0000-rfc-process.md b/text/0000-rfc-process.md index 02fcc011f..8d6516305 100644 --- a/text/0000-rfc-process.md +++ b/text/0000-rfc-process.md @@ -163,7 +163,9 @@ If a single no vote is cast before the arrival of the end date the RFC is immedi The same RFC may be re-opened and brought to a vote again in the future assuming the concerns that lead to the no vote are addressed. -### Amending an RFC +##### Implementation + +##### Amending an RFC While we should strive to get the details right the first time, by doing our due diligence including a proof of concept implementation for larger/riskier RFCs, there will be times when we discover during the process of implementation that something about the original plan was incomplete or needs adjustment. Small changes may be PR'ed by the implementer and merged upon approval by the steward. It is the responsibility of the Steward to determine what changes are minor enough to qualify as an amendment and which are fundamental and/or controversial enough to require a new superseding RFC. @@ -180,9 +182,22 @@ The RFC process should be amended through the RFC process. However, the TOC rese # How it Works [how-it-works]: #how-it-works -### Amending the RFC Process - -The RFC process should be amended through the RFC process. However, the TOC reserves the right to change the process via a super-majority vote in the unlikely even that the process prove so irreparably flawed as to preclude its amendment via the process. +### Labels + +| name | purpose +|---------------------------|-------- +| `type/idea` | An Issues requesting an RFC +| `type/rfc` | A PR containing a new RFC +| `type/tracking` | An issue tracking the implementation of an RFC +| `type/ammendment` | A PR containing an ammendment to an existing RFC +| `scope/project` | Applied to project-level RFCs +| `scope/team` | Applied to team-level RFCs. +| `team/` | E.g `team/platform`. Designates the team that "owns" an RFC. Applies to both team-level and project-level RFCs. For project-level RFCs the lead of this team is the steward. +| `status/needs-steward` | Applied to all new RFCs. Removed once the RFC is accepted by a steward or closed. +| `status/ready-for-review` | The Steward applies this to an RFC when they deem it ready for review by a broader audience. +| `status/voting` | The Steward applies this label when the voting window opens +| `status/accepted` | The Steward applies this label to accepted RFCs. +| `status/rejected` | The Steard applies this label to a rejected RFCs. # Migration [migration]: #migration From 83d8f3a6810e69a2c20314a58fbf980b03c55752 Mon Sep 17 00:00:00 2001 From: Sambhav Kothari Date: Fri, 2 Sep 2022 13:40:29 +0100 Subject: [PATCH 08/10] Apply suggestions from code review Co-authored-by: Natalie Arellano Co-authored-by: Joe Kutner Co-authored-by: Javier Romero --- text/0000-rfc-process.md | 31 +++++++++++++------------------ 1 file changed, 13 insertions(+), 18 deletions(-) diff --git a/text/0000-rfc-process.md b/text/0000-rfc-process.md index 8d6516305..9e2b0d695 100644 --- a/text/0000-rfc-process.md +++ b/text/0000-rfc-process.md @@ -12,7 +12,7 @@ # Summary [summary]: #summary -The "RFC" (request for comments) process provide a consistent and controlled path for new features and other substantive changes to enter the project. +The "RFC" (request for comments) process provides a consistent and controlled path for new features and other substantive changes to enter the project. The RFC process: * provides a set of checkpoints that ensure changes align with the overall technical and strategic vision for the process. @@ -57,7 +57,7 @@ The RFC process **is not**: **Voting Window**: The time period between a call for votes and the voting end date is referred to as the voting window. -**Lazy Consensus**: Voting on project level RFCs is done by lazy consensus. Any project member with a binding vote who has not voted by the end date is assumed to assent to the RFC. +**Lazy Consensus**: Voting on RFCs is done by lazy consensus. Any project member with a binding vote who has not voted by the end date is assumed to assent to the RFC. **Binding Vote**: Binding Votes have formal power within the RFC process. A single no vote by a project member with a binding vote is sufficient to reject an RFC. @@ -80,7 +80,7 @@ As the project grows our process needs to grow with it. Compared to the previous ### What Types of Changes Require an RFC? -Any "substantive" change to the project requires an RFC. substantive includes but is not limited to: +Any "substantive" change to the project should require an RFC. substantive includes but is not limited to: * changes to the specification. * the adoption, creation, or deprecation of a component (e.g. a new platform implementation, a new shared library, a new system buildpack). * new features (e.g. a new pack command, a new flag on an existing pack command, an addition to the buildpack API) @@ -88,7 +88,7 @@ Any "substantive" change to the project requires an RFC. substantive includes bu * any major re-architecture especially if it has noteworthy implications for security or performance. * introduction of new processes or changes to our existing processes including the RFC process. -If there is any doubt, maintainers should prefer opening an "unecessary" RFC to surprising users was unexpectedly impactful changes. +If there is any doubt, maintainers should prefer opening an "unnecessary" RFC over surprising users with unexpectedly impactful changes. #### Project vs Team RFCs @@ -128,7 +128,7 @@ In many but not all cases the appropriate team to own an RFC will be obvious. Wh * Which team is responsible for the components most impacted by the proposed change? * Which team is enthusiastic about supporting the change? -If a home cannot be found for a draft RFC it remains in draft until one can be found. This does not necessary mean that the RFC is not a good idea or isn't something the project will take up eventually. It may simply be that the project does not have the bandwidth to prioritize this particular change at this particular time. +If a home cannot be found for a draft RFC it remains in draft until one can be found. This does not necessarily mean that the RFC is not a good idea or isn't something the project will take up eventually. It may simply be that the project does not have the bandwidth to prioritize this particular change at this particular time. #### Stewardship @@ -149,7 +149,7 @@ The RFC may not be edited during the voting window. For project RFCs, all TOC members and all team leads are given a binding vote. -For team RFCs, all team maintainers are given a binding vote. +Additionally, for team RFCs, all team maintainers are given a binding vote. Votes are cast via reviews on the RFC PR. Accepting the PR signifies a yes vote while a request for changes signifies a no vote. If all members with a binding vote vote in the affirmative, the voting window may close early. @@ -159,7 +159,7 @@ If the end date of the vote arrives without a no vote from a member with binding ##### Rejection -If a single no vote is cast before the arrival of the end date the RFC is immediately rejected and the PR should be closed. +If a single no vote from a member with binding vote is cast before the arrival of the end date the RFC is immediately rejected and the PR should be closed. The same RFC may be re-opened and brought to a vote again in the future assuming the concerns that lead to the no vote are addressed. @@ -197,7 +197,7 @@ The RFC process should be amended through the RFC process. However, the TOC rese | `status/ready-for-review` | The Steward applies this to an RFC when they deem it ready for review by a broader audience. | `status/voting` | The Steward applies this label when the voting window opens | `status/accepted` | The Steward applies this label to accepted RFCs. -| `status/rejected` | The Steard applies this label to a rejected RFCs. +| `status/rejected` | The Steward applies this label to rejected RFCs. # Migration [migration]: #migration @@ -207,30 +207,25 @@ This RFC should be accepted via the existing RFC process. The new process will t # Drawbacks [drawbacks]: #drawbacks -Why should we *not* do this? - -TODO +None # Alternatives [alternatives]: #alternatives -- What other designs have been considered? -- Why is this proposal the best? -- What is the impact of not doing this? - -TODO +None # Prior Art [prior-art]: #prior-art TODO -* Borrows heavily from TEP and KEP processes +* [Tekton Enhancement Proposal Process (TEP)](https://github.com/tektoncd/community/blob/main/teps/0001-tekton-enhancement-proposal-process.md) +* [Kubernetes Enhancement Proposals (KEP)](https://github.com/kubernetes/enhancements/blob/master/keps/README.md) # Unresolved Questions [unresolved-questions]: #unresolved-questions -TODO +None # Spec. Changes (OPTIONAL) [spec-changes]: #spec-changes From 364482e9d10cad4299ae5c7d516e624d6192e721 Mon Sep 17 00:00:00 2001 From: Joe Kutner Date: Thu, 15 Sep 2022 09:33:48 -0500 Subject: [PATCH 09/10] Update text/0000-rfc-process.md Co-authored-by: Aidan Delaney Signed-off-by: Joe Kutner --- text/0000-rfc-process.md | 1 - 1 file changed, 1 deletion(-) diff --git a/text/0000-rfc-process.md b/text/0000-rfc-process.md index 9e2b0d695..d9e994fc0 100644 --- a/text/0000-rfc-process.md +++ b/text/0000-rfc-process.md @@ -217,7 +217,6 @@ None # Prior Art [prior-art]: #prior-art -TODO * [Tekton Enhancement Proposal Process (TEP)](https://github.com/tektoncd/community/blob/main/teps/0001-tekton-enhancement-proposal-process.md) * [Kubernetes Enhancement Proposals (KEP)](https://github.com/kubernetes/enhancements/blob/master/keps/README.md) From 5d8ba9905f135878112d8617e33d27092c2bf5e1 Mon Sep 17 00:00:00 2001 From: Joe Kutner Date: Thu, 15 Sep 2022 09:34:05 -0500 Subject: [PATCH 10/10] Update text/0000-rfc-process.md Co-authored-by: Aidan Delaney Signed-off-by: Joe Kutner --- text/0000-rfc-process.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0000-rfc-process.md b/text/0000-rfc-process.md index d9e994fc0..cfb55ba28 100644 --- a/text/0000-rfc-process.md +++ b/text/0000-rfc-process.md @@ -80,7 +80,7 @@ As the project grows our process needs to grow with it. Compared to the previous ### What Types of Changes Require an RFC? -Any "substantive" change to the project should require an RFC. substantive includes but is not limited to: +Any "substantive" change to the project should require an RFC. Substantive includes but is not limited to: * changes to the specification. * the adoption, creation, or deprecation of a component (e.g. a new platform implementation, a new shared library, a new system buildpack). * new features (e.g. a new pack command, a new flag on an existing pack command, an addition to the buildpack API)