Skip to content

Commit 922d22f

Browse files
michaeltlombardimichaeltlombardi
committed
(RFC) Draft initial RFC guidance
This change adds the `.rfc` folder to the project with draft documentation for the RFC process, an RFC template, and scaffolded folders for accepted RFCs (`.rfc/draft`) implemented RFCs (`.rfc/final`).
1 parent cd13485 commit 922d22f

File tree

6 files changed

+281
-10
lines changed

6 files changed

+281
-10
lines changed

‎.rfc/RFC0000-rfc-process.md

Lines changed: 156 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,156 @@
1+
---
2+
RFC: RFC0000
3+
Author: Mikey Lombardi
4+
Status: Draft
5+
SupercededBy: N/A
6+
Version: 1.0
7+
Area: Process
8+
---
9+
10+
# DSC RFC Process and Guidelines
11+
12+
A DSC RFC (Request for Comments) is a publication to propose design changes and improvements to
13+
DSC. This provides the community an opportunity to provide feedback before code is written where it
14+
becomes harder to change at the risk of compatibility.
15+
16+
This process was adapted from the PowerShell RFC process, which itself was adapted from the Chef
17+
RFC process and the DMTF.org process.
18+
19+
## Roles
20+
21+
- **Author**: All members of the community are allowed to author new RFCs and can provide feedback
22+
to any RFC.
23+
- **DSC Committee**: The design committe that votes to accept or reject an RFC. Currently, the DSC
24+
committee includes the members of the DSC team.
25+
- **Committee Member**: An individual member of the DSC Committee.
26+
- **Working Group (WG)**: A group responsible for deciding whether or not an issue in the
27+
repository requires a proposal and for providing feedback within an RFC proposal.
28+
29+
For more information about Working Groups, see [Working Groups][01].
30+
31+
## Submitting an RFC
32+
33+
When submitting an RFC, the Author shall:
34+
35+
- Create a file named `RFCNNNN-<Title>.md` in the `.rfc/drafts` folder.
36+
37+
The Author _shall not_ assign the RFC number. The author shall leave the `NNNN` in the
38+
filename.
39+
40+
The file must use the [RFC template][02].
41+
42+
Example: `RFCNNNN-docs-extension.md`
43+
- Include any additional files, such as code samples, in the `.rfc/draft/RFCNNNN/` folder.
44+
- Check `Allow edits from maintainers` option when submitting the PR so that the Committee can add
45+
the RFC number to the draft, update the title, and fix the filename.
46+
- Submit the PR as a [draft PR][03].
47+
- Use the prefix `RFC:` for the PR title.
48+
49+
## RFC Status
50+
51+
An RFC may be in any of the following states:
52+
53+
- [Draft](#draft)
54+
- [Reviewing](#reviewing)
55+
- [Accepted](#accepted)
56+
- [Experimental](#experimental)
57+
- [Rejected](#rejected)
58+
- [Withdrawn](#withdrawn)
59+
- [Final](#final)
60+
61+
### Draft
62+
63+
When an RFC is initially submitted as a draft PR, it's in the `Draft` state. RFCs remain in this
64+
state until the Author marks the PR as ready for review.
65+
66+
While an RFC is in this state, we encourage contributors and community members to read, discuss,
67+
and comment on the RFC. Discussion and iteration during the drafting stage provides information
68+
and context for the committee during the reviewing stage.
69+
70+
After one month, the Author may mark their PR as ready for formal review, taking it out of draft. A
71+
Committee member will then apply the `RFC - Reviewing` label to the PR.
72+
73+
### Reviewing
74+
75+
After the author marks their PR as ready for review, the RFC moves into the formal review state.
76+
The RFC remains in this state until one of the following conditions is met:
77+
78+
- The Committee decides to reject the RFC, changing the state to [Rrejected](#rejected).
79+
- The Committee requests an experimental implementation for the RFC, changing the state to
80+
[Experimental](#experimental).
81+
- The Committee decides to accept the RFC as-is, changing the state to [Accepted](#accepted).
82+
- The Author decides to withdraw their RFC, changing the state to [Withdrawn](#withdrawn).
83+
84+
> [!NOTE]
85+
> The Committee may be slower to respond to RFCs where the Author has indicated that they don't
86+
> plan to implement the RFC.
87+
88+
### Rejected
89+
90+
If the Committee decides not to proceed with the RFC, a Committee member shall close the PR instead
91+
of merging it. The Committee should also add the `RFC - Rejected` label to denote that the
92+
Committee rejected the RFC.
93+
94+
In the future, this can be done automatically with GitHub Actions.
95+
96+
### Experimental
97+
98+
Experimental implementations are used to provide a working example of proposed designs in order for
99+
the Committee and other users to understand real-world usage of the proposal.
100+
101+
If the Committee decides to request an experimental implementation, a Committee member shall:
102+
103+
1. Ensure the `status` in the frontmatter of the RFC document is set to `experimental`.
104+
1. Apply the label `RFC - Experimental` to the PR.
105+
1. Update the [RFC History](readme.md#rfc-history) table to reflect the changed status.
106+
1. Merge the PR.
107+
108+
The Author may be asked to continue to update the RFC as the usage of the experimental feature
109+
drives new insight into how the feature should be designed.
110+
111+
When the Committee is satisfied with the experimental implementation, a Committee member will start
112+
the process to finalize the RFC, moving it into the [Final](#final) state.
113+
114+
### Accepted
115+
116+
If the Committee decides to accept the proposal as-is without requesting an experimental
117+
implementation, a Committee member shall:
118+
119+
1. Ensure the `status` in the frontmatter of the RFC document is set to `accepted`.
120+
1. Apply the label `RFC - Accepted` to the PR.
121+
1. Update the [RFC History](readme.md#rfc-history) table to reflect the changed status.
122+
1. Merge the PR.
123+
124+
When the Committee is satisfied with the implementation, a Committee member will start the process
125+
to finalize the RFC, moving it into the [Final](#final) state.
126+
127+
### Withdrawn
128+
129+
If an Author decides to withdraw their RFC, either the Author or a Committee member shall close the
130+
PR without merging it.
131+
132+
A Committee member shall apply the `RFC - Withdrawn` label to the PR, indicating that the author
133+
withdrew the RFC.
134+
135+
### Final
136+
137+
When the Committee is satisfied with the implementation for an RFC, a Committee member will begin
138+
the process to finalize the RFC.
139+
140+
To finalize an RFC, a Committee member shall submit a PR which:
141+
142+
1. Ensures the `status` in the frontmatter of the RFC document is set to `final`.
143+
1. Move the RFC document from the `.rfc/draft` folder to `.rfc/final`.
144+
1. Update the [RFC History](readme.md#rfc-history) table to reflect the changed status.
145+
146+
Any proposed changes should be made through a new RFC or via an issue in the
147+
[PowerShell/DSC repository][04]. New RFCs should reference old RFCs where applicable.
148+
149+
## History
150+
151+
v1.0 - Initial draft.
152+
153+
[01]: https://github.com/PowerShell/PowerShell/blob/master/docs/community/working-group.md
154+
[02]: RFCNNNN-New-RFC-Template.md
155+
[03]: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests#draft-pull-requests
156+
[04]: https://github.com/powershell/dsc

‎.rfc/RFCNNNN-New-RFC-Template.md

Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,73 @@
1+
---
2+
RFC: RFC<four digit unique incrementing number assigned by Committee, this shall be left blank by the author>
3+
Author: <First Last>
4+
Status: <Draft | Experimental | Accepted | Rejected | Withdrawn | Final>
5+
SupercededBy: <link to another RFC>
6+
Version: <Major>.<Minor>
7+
Area: <Area within the DSC project>
8+
Comments Due: <Date for submitting comments to current draft (minimum 1 month)>
9+
Plan to implement: <Yes | No>
10+
---
11+
12+
# Title
13+
14+
<!--
15+
Write a summary of your proposal in this section. Make sure to change the title to reflect
16+
your proposal.
17+
-->
18+
19+
## Motivation
20+
21+
<!--
22+
Indicate the value of the proposal in this section. Start with a brief user story following
23+
this template:
24+
25+
> As a <persona>,
26+
> I want <functionality>,
27+
> so that <benefit>.
28+
29+
Replace the terms at the end of each line:
30+
31+
- <persona> should clarify _who_ the proposal primarily benefits.
32+
- <functionality> should indicate what effective change the proposal represents.
33+
- <benefit> should include one or more ways the proposal improves the experience for the
34+
<persona>.
35+
36+
You can define more than one user story.
37+
38+
After the user story, you may provide additional context expanding on the proposal.
39+
-->
40+
41+
## Proposed experience
42+
43+
<!--
44+
Demonstrate an example of how the RFC will affect user or developer experience in this
45+
section. Include examples of input and output.
46+
-->
47+
48+
## Specification
49+
50+
<!--
51+
Define as specifically as possible your proposal with the technical requirements in this
52+
section. If possible, include relevant JSON Schemas for proposed changes to data types, input,
53+
and output.
54+
-->
55+
56+
## Alternate Proposals and Considerations
57+
58+
<!--
59+
Include any alternate proposals and notes for the RFC in this section.
60+
-->
61+
62+
## Related work items
63+
64+
<!--
65+
Include any relevant GitHub issues, discussions, and pull requests as unordered list items
66+
in this section. If the work item title doesn't clearly indicate how it relates to this
67+
RFC, add a short summary statement after the work item.
68+
69+
For example:
70+
71+
- #123 - Indicates the need for and prior conversation around discovering DSC resources from
72+
remote registries.
73+
-->

‎.rfc/draft/.gitkeep

Whitespace-only changes.

‎.rfc/final/.gitkeep

Whitespace-only changes.

‎.rfc/readme.md

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
# Desired State Configuration RFC
2+
3+
This folder contains RFC documents for community feedback on proposed changes and improvements
4+
5+
See [RFC0000: RFC-Process][01] for process information.
6+
7+
Along with making DSC open source, we're also inviting the community to author RFCs on proposed
8+
design changes (instead of having long threads in issues). The DSC team will meet at least once per
9+
month (more frequently, depending on amount of feedback) to review and respond.
10+
11+
We'll continue to refine this process as we learn from it.
12+
13+
## RFC History
14+
15+
The following table shows the RFCs that have been reviewed and processed by the committee. It
16+
doesn't include draft RFCs.
17+
18+
<!--
19+
After an RFC PR is merged or closed, a maintainer should update this table to include a new
20+
entry for the RFC. You can use the `rfc-table-entry` snippet in VS Code to create the new
21+
entry.
22+
23+
Use the pull requests column to link to the associated PR for the RFC. You can use the autolink
24+
functionality and reference the pull request by number, like `#123`.
25+
26+
For RFCs in the accepted, experimental, or final state, update the entry in the RFC column to
27+
point to the merged document.
28+
-->
29+
30+
| RFC | Title | Status | Pull Requests |
31+
|:-------:|:-------------------------------|:------:|:--------------|
32+
| RFC0000 | DSC RFC Process and Guidelines | Draft | |
33+
34+
[01]: RFC0000-rfc-process.md

‎.vscode/docs.code-snippets

Lines changed: 18 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,9 @@
11
{
2-
// Place your DSCv3 workspace snippets here. Each snippet is defined under a snippet name and has a scope, prefix, body and
3-
// description. Add comma separated ids of the languages where the snippet is applicable in the scope field. If scope
4-
// is left empty or omitted, the snippet gets applied to all languages. The prefix is what is
5-
// used to trigger the snippet and the body will be expanded and inserted. Possible variables are:
6-
// $1, $2 for tab stops, $0 for the final cursor position, and ${1:label}, ${2:another} for placeholders.
2+
// Place your DSCv3 workspace snippets here. Each snippet is defined under a snippet name and has a scope, prefix, body and
3+
// description. Add comma separated ids of the languages where the snippet is applicable in the scope field. If scope
4+
// is left empty or omitted, the snippet gets applied to all languages. The prefix is what is
5+
// used to trigger the snippet and the body will be expanded and inserted. Possible variables are:
6+
// $1, $2 for tab stops, $0 for the final cursor position, and ${1:label}, ${2:another} for placeholders.
77
// Placeholders with the same ids are connected.
88
"Configuration function template": {
99
"scope": "markdown",
@@ -140,7 +140,7 @@
140140
" </details>",
141141
""
142142
]
143-
}
143+
},
144144
"Changelog Entry Multi Item": {
145145
"scope": "markdown",
146146
"prefix": "docs-changelog-entry-multi-issue-pr",
@@ -158,7 +158,7 @@
158158
" </details>",
159159
""
160160
]
161-
}
161+
},
162162
"Changelog release heading": {
163163
"scope": "markdown",
164164
"prefix": "docs-changelog-release-heading",
@@ -173,14 +173,22 @@
173173
"[release-${1:v3.0.0-${2:alpha.5}}]: https://github.com/PowerShell/DSC/releases/tag/${1:v3.0.0-${2:alpha.5}} \"Link to the DSC ${1:v3.0.0-${2:alpha.5}} release on GitHub\"",
174174
"[compare-${1:v3.0.0-${2:alpha.5}}]: https://github.com/PowerShell/DSC/compare/v3.0.0-alpha.4...${1:v3.0.0-${2:alpha.5}}"
175175
]
176-
177-
}
176+
},
178177
"Github Work Item Link": {
179178
"scope": "markdown",
180179
"prefix": "docs-gh-link",
181180
"description": "Template for a DSC Github work item link",
182181
"body": [
183182
"[#${1:work item id}]: https://github.com/PowerShell/DSC/issues/${1:work item id}"
184183
]
185-
}
184+
},
185+
"RFC table entry": {
186+
"scope": "markdown",
187+
"prefix": "rfc-table-entry",
188+
"description": "Template for an entry in the RFC History table",
189+
"body": [
190+
"| RFC${1:NNNN} | ${2:Title} | ${3|Accepted,Rejected,Final|} | ${4:#123} |"
191+
]
192+
},
193+
186194
}

0 commit comments

Comments
 (0)