Skip to content

Commit ef60c25

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 56910ef commit ef60c25

File tree

6 files changed

+321
-10
lines changed

6 files changed

+321
-10
lines changed

‎.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
}

‎rfc/RFC0000-rfc-process.md

Lines changed: 196 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,196 @@
1+
---
2+
RFC: RFC0000
3+
Author: @michaeltlombardi
4+
Sponsor: @michaeltlombardi
5+
Status: Draft
6+
SupercededBy: null
7+
Version: 1.0
8+
Area: Process
9+
CommentsDue: 2025-07-06
10+
---
11+
12+
# DSC RFC Process and Guidelines
13+
14+
A DSC RFC (Request for Comments) is a publication to propose design changes and improvements to
15+
DSC. This provides the community an opportunity to provide feedback before code is written where it
16+
becomes harder to change at the risk of compatibility.
17+
18+
This process was adapted from the [PowerShell RFC process][01].
19+
20+
## Roles
21+
22+
- **Author**: All members of the community are allowed to author new RFCs and can provide feedback
23+
to any RFC.
24+
- **Working Group (WG)**: A group responsible for deciding whether or not an issue in the
25+
repository requires a proposal and for providing feedback within an RFC proposal and votes to
26+
accept or reject an RFC.
27+
28+
For more information about Working Groups, see [Working Groups][02].
29+
- **Sponsor**: A person who commits to implementing an RFC if the WG accepts it. The sponsor may be
30+
the Author, a WG member, or any member of the community. The WG won't accept an RFC proposal
31+
without a Sponsor.
32+
33+
## When to submit an RFC
34+
35+
Generally, you should submit proposals as [issues in the DSC repository][03]. When reviewing
36+
issues, the WG may request an RFC. The issue author, a WG member, or any other memberof the
37+
community may then draft and submit an RFC for the issue.
38+
39+
WG members may also submit an RFC for proposals arising from WG discussions, knowing that the
40+
proposal is complex enough to warrant a full RFC.
41+
42+
## Submitting an RFC
43+
44+
When submitting an RFC, the Author shall:
45+
46+
- Create a file named `RFCNNNN-<Title>.md` in the `rfc/drafts` folder.
47+
48+
The Author _shall not_ assign the RFC number. The author shall leave the `NNNN` in the
49+
filename. Example: `RFCNNNN-docs-extension.md`
50+
51+
The file must use the [RFC template][04]. The Author must fill out the following fields in the
52+
template frontmatter:
53+
54+
- `Author` - Set to your GitHub username prefixed with `@`, like `@MyUserName`.
55+
- `Status` - Set to `Draft`.
56+
- `Version` - Set to `1.0`.
57+
- `CommentsDue` - Set to a date at least one month from the date you intend to submit the PR. Use
58+
[ISO8601][05] format, like `2022-09-27` for September 27, 2022.
59+
60+
Set the `Sponsor` field to your GitHub username if you're willing to implement the RFC, assuming
61+
the WG accepts it.
62+
63+
Define the H1 title. Fill out each section of the template as directed by the template comments.
64+
- Include any additional files, such as code samples, in the `rfc/draft/RFCNNNN/` folder.
65+
- Check `Allow edits from maintainers` option when submitting the PR so that the WG can add the RFC
66+
number to the draft, update the title, and fix the filename.
67+
- Submit the PR as a [draft PR][06].
68+
- Use the prefix `RFC:` for the PR title.
69+
70+
## Sponsoring an RFC
71+
72+
At any time while the RFC is in the [Draft](#draft) or [Reviewing](#reviewing) state, the Author, a
73+
WG member, or community member may choose to sponsor the RFC by committing to implement it, if
74+
accepted.
75+
76+
When a Sponsor commits to the RFC, a WG member will:
77+
78+
1. Apply the `RFC - Sponsored` label to the PR.
79+
1. Assign the PR to the Sponsor.
80+
1. Set the `Sponsor` field of the draft RFC to the GitHub username of the Sponsor.
81+
82+
The WG will only accept RFCs with a Sponsor.
83+
84+
## RFC Status
85+
86+
An RFC may be in any of the following states:
87+
88+
- [Draft](#draft)
89+
- [Reviewing](#reviewing)
90+
- [Accepted](#accepted)
91+
- [Experimental](#experimental)
92+
- [Rejected](#rejected)
93+
- [Withdrawn](#withdrawn)
94+
- [Final](#final)
95+
96+
### Draft
97+
98+
When an RFC is initially submitted as a draft PR, it's in the `Draft` state. RFCs remain in this
99+
state until the Author marks the PR as ready for review.
100+
101+
While an RFC is in this state, we encourage contributors and WG members to read, discuss, and
102+
comment on the RFC. Discussion and iteration during the drafting stage provides information and
103+
context for the WG during the reviewing stage.
104+
105+
After one month, the Author may mark their PR as ready for formal review, taking it out of draft. A
106+
WG member will then apply the `RFC - Reviewing` label to the PR.
107+
108+
### Reviewing
109+
110+
After the author marks their PR as ready for review, the RFC moves into the formal review state.
111+
112+
The RFC remains in this state until one of the following conditions is met:
113+
114+
- The WG decides to reject the RFC, changing the state to [Rejected](#rejected).
115+
- The RFC has a [Sponsor](#sponsoring-an-rfc) and the WG requests an experimental implementation,
116+
changing the state to [Experimental](#experimental).
117+
- The RFC has a [Sponsor](#sponsoring-an-rfc) and the WG decides to accept the RFC as-is, changing
118+
the state to [Accepted](#accepted).
119+
- The Author decides to withdraw their RFC, changing the state to [Withdrawn](#withdrawn).
120+
121+
### Rejected
122+
123+
If the WG decides not to proceed with the RFC, a WG member shall:
124+
125+
1. Add a comment to the PR indicating the rationale for rejecting the RFC.
126+
1. Add the `RFC - Rejected` label to denote that the WG rejected the RFC.
127+
1. Close the PR instead of merging it.
128+
1. Update the [RFC History][07] table to reflect the changed status.
129+
130+
In the future, this can be done automatically with GitHub Actions.
131+
132+
### Experimental
133+
134+
Experimental implementations are used to provide a working example of proposed designs in order for
135+
the WG and other users to understand real-world usage of the proposal.
136+
137+
If the WG decides to request an experimental implementation, a WG member shall:
138+
139+
1. Ensure the `Status` in the frontmatter of the RFC document is set to `Experimental`.
140+
1. Apply the label `RFC - Experimental` to the PR.
141+
1. Update the [RFC History][07] table to reflect the changed status.
142+
1. Merge the PR.
143+
144+
The Author may be asked to continue to update the RFC as the usage of the experimental feature
145+
drives new insight into how the feature should be designed.
146+
147+
When the WG is satisfied with the experimental implementation, a WG member will start
148+
the process to finalize the RFC, moving it into the [Final](#final) state.
149+
150+
### Accepted
151+
152+
If the WG decides to accept the proposal as-is without requesting an experimental
153+
implementation, a WG member shall:
154+
155+
1. Ensure the `Status` in the frontmatter of the RFC document is set to `Accepted`.
156+
1. Apply the label `RFC - Accepted` to the PR.
157+
1. Update the [RFC History][07] table to reflect the changed status.
158+
1. Merge the PR.
159+
160+
When the WG is satisfied with the implementation, a WG member will start the process
161+
to finalize the RFC, moving it into the [Final](#final) state.
162+
163+
### Withdrawn
164+
165+
If an Author decides to withdraw their RFC, either the Author or a WG member shall close the
166+
PR without merging it.
167+
168+
A WG member shall apply the `RFC - Withdrawn` label to the PR, indicating that the author
169+
withdrew the RFC.
170+
171+
### Final
172+
173+
When the WG is satisfied with the implementation for an RFC, a WG member will begin
174+
the process to finalize the RFC.
175+
176+
To finalize an RFC, a WG member shall submit a PR which:
177+
178+
1. Ensures the `Status` in the frontmatter of the RFC document is set to `Final`.
179+
1. Move the RFC document from the `rfc/draft` folder to `rfc/final`.
180+
1. Update the [RFC History][07] table to reflect the changed status.
181+
182+
Any proposed changes should be made through a new RFC or as an issue in the
183+
[PowerShell/DSC repository][08]. New RFCs should reference old RFCs where applicable.
184+
185+
## History
186+
187+
v1.0 - Initial draft.
188+
189+
[01]:https://github.com/PowerShell/PowerShell-RFC/blob/master/RFC0000-RFC-Process.md
190+
[02]: https://github.com/PowerShell/PowerShell/blob/master/docs/community/working-group.md
191+
[03]: https://github.com/PowerShell/DSC/issues/new/choose
192+
[04]: RFCNNNN-New-RFC-Template.md
193+
[05]: 2022-09-27
194+
[06]: 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
195+
[07]: readme.md#rfc-history
196+
[08]: 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: RFCNNNN # WG will set the number after submission
3+
Author: null # <@GitHubUserName>
4+
Sponsor: null # <@GitHubUserName>
5+
Status: Draft # <Draft | Experimental | Accepted | Final>
6+
SupercededBy: null # <Superceding RFC Number>
7+
Version: 1.0 # <Major>.<Minor>
8+
Area: null # <Area within the DSC project>
9+
CommentsDue: null # <Date for submitting comments to current draft (minimum 1 month)>
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 | #868 |
33+
34+
[01]: RFC0000-rfc-process.md

0 commit comments

Comments
 (0)