mirror of
https://github.com/opentofu/opentofu.git
synced 2025-02-25 18:45:20 -06:00
New RFC process (#1669)
Signed-off-by: Janos <86970079+janosdebugs@users.noreply.github.com> Signed-off-by: Christian Mesh <christianmesh1@gmail.com> Co-authored-by: James Humphries <James@james-humphries.co.uk> Co-authored-by: Christian Mesh <christianmesh1@gmail.com> Co-authored-by: Siddhartha Sonker <158144589+siddharthasonker95@users.noreply.github.com> Co-authored-by: Ronny Orot <ronny.orot@gmail.com> Co-authored-by: Oleksandr Levchenkov <ollevche@gmail.com>
This commit is contained in:
Janos
GitHub
parent
5a161c8bcc
commit
bfe5a4cd13
138
.github/ISSUE_TEMPLATE/rfc.yml
vendored
138
.github/ISSUE_TEMPLATE/rfc.yml
vendored
@ -1,138 +0,0 @@
|
||||
# Copyright (c) The OpenTofu Authors
|
||||
# SPDX-License-Identifier: MPL-2.0
|
||||
# Copyright (c) 2023 HashiCorp, Inc.
|
||||
# SPDX-License-Identifier: MPL-2.0
|
||||
|
||||
# This RFC has been inspired by the Rust RFC template https://github.com/rust-lang/rfcs/blob/master/0000-template.md
|
||||
|
||||
name: Submit RFC
|
||||
description: Submit a highly-structured change request for public discussion.
|
||||
labels: ["rfc", "pending-decision"]
|
||||
body:
|
||||
- type: markdown
|
||||
attributes:
|
||||
value: |
|
||||
Thank you for opening an RFC!
|
||||
|
||||
RFCs are a highly-structured format for submitting change requests. All major changes to OpenTofu should first go through an RFC, to have a place for the community to discuss.
|
||||
|
||||
The template has a lot of fields and is inspired by the Rust RFC template. Please take your time to fill it out carefully.
|
||||
|
||||
Working experimental PoCs in a draft Pull Request are a very welcome attachment to an RFC, especially ones that are easy to check out and take for a spin.
|
||||
|
||||
- type: textarea
|
||||
id: summary
|
||||
attributes:
|
||||
label: Summary
|
||||
description: |
|
||||
One paragraph explanation of the feature.
|
||||
placeholder:
|
||||
value:
|
||||
validations:
|
||||
required: true
|
||||
|
||||
- type: textarea
|
||||
id: problem-statement
|
||||
attributes:
|
||||
label: Problem Statement
|
||||
description: |
|
||||
Why are we doing this? What problem are we solving?
|
||||
placeholder:
|
||||
value:
|
||||
validations:
|
||||
required: true
|
||||
|
||||
- type: textarea
|
||||
id: user-facing-description
|
||||
attributes:
|
||||
label: User-facing description
|
||||
description: |
|
||||
Please describe in detail how the feature would work from the perspective of somebody using:
|
||||
- How can the feature be used?
|
||||
- How would you explain the feature to somebody?
|
||||
- Please provide examples of the feature in action.
|
||||
|
||||
placeholder:
|
||||
value:
|
||||
validations:
|
||||
required: true
|
||||
|
||||
- type: textarea
|
||||
id: technical-description
|
||||
attributes:
|
||||
label: Technical Description
|
||||
description: |
|
||||
Please describe in detail how the feature would work from a technical perspective:
|
||||
- Which components of OpenTofu would be involved in the change?
|
||||
- How would the components need to change?
|
||||
- Are there any interactions with other features that should be mentioned?
|
||||
- Are the any edge cases of the feature that should be discussed?
|
||||
placeholder:
|
||||
value:
|
||||
validations:
|
||||
required: true
|
||||
|
||||
- type: textarea
|
||||
id: rationale-and-alternatives
|
||||
attributes:
|
||||
label: Rationale and alternatives
|
||||
description: |
|
||||
- What would be the impact of this feature?
|
||||
- Why is this solution better than alternative solutions to this problem, if there are any?
|
||||
- How would the OpenTofu user experience suffer if we didn't do this.
|
||||
placeholder:
|
||||
value:
|
||||
validations:
|
||||
required: true
|
||||
|
||||
- type: textarea
|
||||
id: downsides
|
||||
attributes:
|
||||
label: Downsides
|
||||
description: |
|
||||
- Are there any disadvantages of implementing this?
|
||||
placeholder:
|
||||
value:
|
||||
validations:
|
||||
required: false
|
||||
|
||||
- type: textarea
|
||||
id: unresolved-questions
|
||||
attributes:
|
||||
label: Unresolved Questions
|
||||
description: |
|
||||
- Are there any specific parts of the feature you're not sure about?
|
||||
- Are there any specific parts of the technical implementation you're not sure about?
|
||||
- Are there any other questions or unknowns that need to be answered before implementing this?
|
||||
placeholder:
|
||||
value:
|
||||
validations:
|
||||
required: false
|
||||
|
||||
- type: textarea
|
||||
id: related-issues
|
||||
attributes:
|
||||
label: Related Issues
|
||||
description: |
|
||||
- Please post any issues or RFCs related to this one.
|
||||
placeholder:
|
||||
value:
|
||||
validations:
|
||||
required: false
|
||||
|
||||
- type: textarea
|
||||
id: poc-pull-request
|
||||
attributes:
|
||||
label: Proof of Concept
|
||||
description: |
|
||||
- If there is a Pull Request with a Proof of Concept, please link it here.
|
||||
- Please concisely describe how to take the PoC for a spin.
|
||||
placeholder:
|
||||
value:
|
||||
validations:
|
||||
required: false
|
||||
|
||||
- type: markdown
|
||||
attributes:
|
||||
value: |
|
||||
**Note:** If the submit button is disabled and you have filled out all required fields, please check that you did not forget a **Title** for the issue.
|
||||
@ -7,7 +7,7 @@ Welcome and thank you for wanting to contribute!
|
||||
- Have a question? Post it in [GitHub Discussions ➡️](https://github.com/orgs/opentofu/discussions) or on the [OpenTofu Slack ➡️](https://opentofu.org/slack/)!
|
||||
- Found a bug? [Report it here ➡️](https://github.com/opentofu/opentofu/issues/new?assignees=&labels=bug%2Cpending-decision&projects=&template=bug_report.yml)
|
||||
- Have a feature idea? [Submit it here ➡️](https://github.com/opentofu/opentofu/issues/new?assignees=&labels=enhancement%2Cpending-decision&projects=&template=feature_request.yml)
|
||||
- Want to provide detailed documentation on a feature idea? [Write an RFC here ➡️](https://github.com/opentofu/opentofu/issues/new?assignees=&labels=rfc%2Cpending-decision&projects=&template=rfc.yml)
|
||||
- Want to help define a complex feature or bug fix? [Write an RFC here ➡️](./rfc/README.md)
|
||||
- Want to provide a proof-of-concept for an issue? Please [submit a draft PR here ➡️](https://github.com/opentofu/opentofu/compare)
|
||||
- Want to add a feature, fix a linter error, refactor something, or add CI tooling?
|
||||
1. Check if there is an [open issue with the `accepted` label](https://github.com/opentofu/opentofu/issues?q=is%3Aopen+is%3Aissue+label%3Aaccepted),
|
||||
@ -369,7 +369,7 @@ Depending on the core team's review, a feature request can have the following ou
|
||||
|
||||
1. **The feature is accepted for development by the core team.** This means that the core team will schedule it for an upcoming release and develop it.
|
||||
2. **The feature is accepted and open for community contributions.** The core team adds a `help wanted` label and waits for community volunteers to develop it.
|
||||
3. **More information is needed.** The core team will either add questions in comments, or when there is a deep technical issue to be resolved, call for an RFC to detail a possible implementation.
|
||||
3. **More information is needed.** The core team will either add questions in comments, or when there is a deep technical issue to be resolved, call for an [RFC](./rfc/README.md) to detail a possible implementation.
|
||||
4. **More community input is needed.** When an issue is, on its surface, valuable, but there is no track record of a large portion of the community needing it, the core team adds the `needs community input` label. If you are interested in the feature and would like to use it, please add a reaction to the issue and add a description on specifically what problem it would solve for you in a comment.
|
||||
5. **The feature is rejected.** If based on the criteria above it is not feasible to implement the feature, the core team closes the issue with an explanation why it is being closed.
|
||||
6. **The feature is referred to the Technical Steering Committee**. If the feature requires the commitment of a larger amount of core developer time, has legal implications, or otherwise requires leadership attention, the core team adds the feature to the agenda of the Technical Leadership Committee. Once decided, the TSC records the decision in the [TSC_SUMMARY.md](TSC_SUMMARY.md) file.
|
||||
@ -398,10 +398,10 @@ First of all, thank you for volunteering! Before you begin coding, please take a
|
||||
- [`bug`](https://github.com/opentofu/opentofu/labels/bug): it's broken and needs to be fixed.
|
||||
- [`enhancement`](https://github.com/opentofu/opentofu/labels/enhancement): it's a short-form feature request. If the implementation path is unclear, an `rfc` may be needed in addition.
|
||||
- [`documentation`](https://github.com/opentofu/opentofu/labels/documentation): something that needs a description on the OpenTofu website.
|
||||
- [`rfc`](https://github.com/opentofu/opentofu/labels/rfc): a long-form feature request with details on how exactly it should be implemented.
|
||||
- [`rfc`](https://github.com/opentofu/opentofu/labels/rfc): a long-form discussion on building a feature or solving bug, see [RFC](./rfc/README.md).
|
||||
- [`question`](https://github.com/opentofu/opentofu/labels/question): the core team needs more information on the issue to decide.
|
||||
- [`needs-community-input`](https://github.com/opentofu/opentofu/labels/needs-community-input): the core team needs to see how many people are affected by this issue. You can provide feedback by using reactions on the issue and adding your use case in the comments. (Please describe what problem it would solve for you specifically.)
|
||||
- [`needs-rfc`](https://github.com/opentofu/opentofu/labels/needs-rfc): this issue needs a detailed technical description on how it would be implemented in the form of an RFC.
|
||||
- [`needs-rfc`](https://github.com/opentofu/opentofu/labels/needs-rfc): this issue needs a detailed technical description on how it would be implemented in the form of an [RFC](./rfc/README.md).
|
||||
|
||||
---
|
||||
|
||||
|
||||
85
rfc/20240524-OpenTofu-RFC-Process.md
Normal file
85
rfc/20240524-OpenTofu-RFC-Process.md
Normal file
@ -0,0 +1,85 @@
|
||||
# OpenTofu RFC Process
|
||||
|
||||
Issue: <N/A>
|
||||
|
||||
As the OpenTofu project evolves, the community has been proposing more advanced concepts and ideas that frequently need significant discussion and iterations of feedback. Our Current RFC Process is cumbersome and hard to follow due to the following limitations: single user can edit, pages of comments are overwhelming, sub discussions are not easily possible.
|
||||
|
||||
As we move forward, a new more transparent and flexible RFC process is needed. We start by investigating the other successful open source communities with similar goals.
|
||||
* https://github.com/rust-lang/rfcs/blob/master/0000-template.md
|
||||
* https://peps.python.org/pep-0001/
|
||||
* https://github.com/openshift/enhancements
|
||||
|
||||
These popular and well tested solutions all follow a similar format:
|
||||
1. Single file to track an RFC committed to the repo
|
||||
2. Markdown format used in most cases
|
||||
3. Public GitHub Pull Request serves as a dynamic avenue for discussions and threads therein
|
||||
4. Easily proposed feedback in the form of `suggestions` and pull requests
|
||||
5. Template provided as a starting point, but not a rigid requirement
|
||||
|
||||
## Proposed Solution
|
||||
|
||||
OpenTofu should adopt a Pull Request based RFC process and should introduce the process with the understanding that it will be modified as we gain experience with it.
|
||||
|
||||
### User Documentation
|
||||
|
||||
#### Readers of RFCs
|
||||
|
||||
Community Members use RFCs in two main ways:
|
||||
1. Implementing a concept that has been discussed
|
||||
2. Learning about the OpenTofu Project and understanding previous decisions made
|
||||
|
||||
Both of these users will be looking for a single location, which contains organized RFC documents which have been approved.
|
||||
|
||||
We therefore propose that Markdown files which contain RFCs are located within the `./rfc` folder in the main OpenTofu Repository. This folder will contain files that follow the format of `./rfc/${isodate}-${rfc title}.md`, which allows easy searching and sorting of accepted RFCs. Additionally, RFCs that have not yet been accepted will exist as Pull Requests labeled with `rfc`.
|
||||
|
||||
In the case that a single MD file is not sufficient for describing a RFC, a folder named `./rfc/${isodate}-${rfc title}` should be created to contain supplementary information such as diagrams or detailed technical explorations. These supplementary files should be linked to from the main Markdown file for the RFC.
|
||||
|
||||
RFCs should link to the issue(s) that originally required the more in-depth process that an RFC provides. Additionally, issues which are created to track the implementation of an RFC will link to that RFC. This allows anyone encountering each of these distinct pieces to easily gather a view of the whole process.
|
||||
|
||||
#### RFC Authors and Reviewers
|
||||
|
||||
The following will be split between [CONTRIBUTING.md](../CONTRIBUTING.md) and [rfc/README.md](./README.md):
|
||||
|
||||
The process starts with an issue (`enhancement` or `bug`) is submitted to the repository. The `needs-rfc` label is added during the Core Team Triage process and indicates that an in-depth discussion and consensus is needed. This facilitates conversations and discussions around complex issues that are hard to have in the GitHub Issue format.
|
||||
|
||||
If interested, a Community Member will take the following actions to submit an RFC:
|
||||
1. Copy the [./rfc/yyyymmdd-template.md](link) to `./rfc/${isodate}-${rfc title}.md` on a branch in their fork of the OpenTofu Repository
|
||||
2. Edit the newly created Markdown file and fill in the template fields
|
||||
3. Submit a Pull Request in the OpenTofu Repository, linked to the open issue(s)
|
||||
- A Draft Pull Request is recommended if early feedback or help is needed to fully fill out the template
|
||||
4. The Community Members discuss the RFC in detail until all open questions are resolved
|
||||
5. The majority of the Core Team Approves the RFC Pull Request
|
||||
- The Team Lead has the ability veto an RFC or to escalate to the Technical Steering Committee
|
||||
- If a consensus is not reached, the Pull Request is closed.
|
||||
- The Core Team may ask for a new RFC or may close the original issue entirely.
|
||||
6. The RFC is Merged, and the Core Team creates issues in the relevant repositories to track the work required to implement the RFC.
|
||||
|
||||
### Technical Approach
|
||||
|
||||
No automation is proposed as part of this process, however we are using the RFC Template proposed in this PR to "dog-food" the process.
|
||||
|
||||
No additional labels are required in the repository.
|
||||
|
||||
Updates to the CONTRIBUTING.md are required as described above and the existing RFC template will need to be removed.
|
||||
|
||||
### Open Questions
|
||||
|
||||
* Should we use ISODATE or assigned SERIAL in the RFC file name
|
||||
- ISODATE could either be proposed date or accepted date
|
||||
- SERIAL is clearly linear, but requires additional processing once the PR is Accepted.
|
||||
- For now we are using proposed date, but automation could easily be added to amend the RFC once it has been merged.
|
||||
* Should we backport some or all of the current RFCs accepted into OpenTofu to additionally validate this process?
|
||||
|
||||
### Future Considerations
|
||||
|
||||
#### Moving to a separate repository
|
||||
|
||||
For now, we are proposing to keep all of the RFC files in the main OpenTofu Repository. We believe that this helps with discoverability and co-locates it with the majority of the ongoing development effort. This does have some downsides however, primarily in waiting on the required GitHub actions (testing) that are run for all pull requests. If we ever decide to change this location to either RFCs in a single separate repository or per-repository, the specific history can easily be pulled over using standard git commands.
|
||||
|
||||
As mentioned in [Open Questions](#Open-Questions), we may build automation using GitHub Actions to post-process RFCs once they are accepted and merged.
|
||||
|
||||
## Potential Alternatives
|
||||
|
||||
The main alternative to this process is to keep the existing process. It does work in some capacity despite the limitations described above.
|
||||
|
||||
There are more "formal" RFC processes such as the [IETF RFCs](https://en.wikipedia.org/wiki/List_of_RFCs). We don't believe we need that level of formality and detail at this juncture.
|
||||
25
rfc/README.md
Normal file
25
rfc/README.md
Normal file
@ -0,0 +1,25 @@
|
||||
# The OpenTofu RFCs
|
||||
|
||||
This folder contains Request For Comment (RFC) documents that have been discussed, reviewed, and accepted. They represent a proposal of changes to one or more of the repositories in the OpenTofu organization.
|
||||
|
||||
RFCs are primarily created by the OpenTofu Community in response to one or more GitHub issues that require a more in-depth discussion than the GitHub Issue process can provide. They are organized by date to help show the progression of concepts over time.
|
||||
|
||||
## Authoring an RFC
|
||||
|
||||
When an Issue is given the `needs-rfc` label, any community member may propose an RFC by following these steps:
|
||||
1. Copy the [./rfc/yyyymmdd-template.md](link) to `./rfc/${isodate}-${rfc title}.md` on a branch in their fork of the OpenTofu Repository
|
||||
2. Edit the newly created Markdown file and fill in the template fields
|
||||
3. Submit a Pull Request in the OpenTofu Repository, linked to the open issue(s)
|
||||
|
||||
> [!NOTE]
|
||||
> It's ok to file an incomplete RFC. Please submit it as a draft pull request to get early feedback.
|
||||
|
||||
Once an RFC is submitted, community members discuss the RFC in detail until all open questions are resolved
|
||||
|
||||
To Accept an RFC, the majority of the OpenTofu [Core Team](../MAINTAINERS) must approve the Pull Request. If a consensus is not reached, the Pull Request is closed and the Core Team may ask for a new RFC or close the original issue entirely.
|
||||
|
||||
Once an RFC is Accepted and Merged, the Core Team creates issues in the relevant repositories to track the work required to implement the RFC.
|
||||
|
||||
## Amending an RFC
|
||||
|
||||
RFCs are not set in stone, Approval signifies that an initial consensus has been reached and work can be started. If you realize that parts of the implementation won't work, feel free to amend the RFC in a subsequent PR. Doing so will serve as an important point of discussion if something doesn't go according to plan.
|
||||
39
rfc/yyyymmdd-template.md
Normal file
39
rfc/yyyymmdd-template.md
Normal file
@ -0,0 +1,39 @@
|
||||
# RFC Title
|
||||
|
||||
Issue: https://github.com/OpenTofu/{ Repository }/issues/{ issue number } <!-- Ideally, this issue will have the "needs-rfc" label added by the Core Team during triage -->
|
||||
|
||||
A short description of the problem that is trying to be solved. Include links to existing documentation, code examples, and links to existing code. Written such that a non-technical user or someone unfamiliar with the OpenTofu code will be able to understand and discuss it.
|
||||
|
||||
Background on the issue with links to similar problems which have been resolved in the past.
|
||||
|
||||
## Proposed Solution
|
||||
|
||||
Overview of the Proposed Solution to introduce the User Documentation and Technical Approach.
|
||||
|
||||
### User Documentation
|
||||
|
||||
Describe what the user would encounter when attempting to interact with what is being proposed. Provide clear and detailed descriptions, code examples, diagrams, etc... Starting point for the documentation that will be added during implementation.
|
||||
|
||||
This documentation will help the community have a better understanding how they will be interacting with this proposal and have an easier time discussing it in depth.
|
||||
|
||||
### Technical Approach
|
||||
|
||||
Technical summary, easy to understand by someone unfamiliar with the codebase.
|
||||
|
||||
Link to existing documentation and code, include diagrams if helpful.
|
||||
|
||||
Include pseudocode or link to a Proof of Concept if applicable.
|
||||
|
||||
Describe potential limitations or impacts on other areas of the codebase.
|
||||
|
||||
### Open Questions
|
||||
|
||||
List questions that should be discussed and answered during the RFC process.
|
||||
|
||||
### Future Considerations
|
||||
|
||||
What are some potential future paths this solution could take? What other features may interact with this solution, what should be kept in mind during implementation?
|
||||
|
||||
## Potential Alternatives
|
||||
|
||||
List different approaches and briefly compare with the proposal in this RFC. It's important to explore and understand possible alternatives before agreeing on a solution.
|
||||
Loading…
Reference in New Issue
Block a user