diff --git a/.vscode/docs.code-snippets b/.vscode/docs.code-snippets index 839aac127..b6643622e 100644 --- a/.vscode/docs.code-snippets +++ b/.vscode/docs.code-snippets @@ -1,9 +1,9 @@ { - // Place your DSCv3 workspace snippets here. Each snippet is defined under a snippet name and has a scope, prefix, body and - // description. Add comma separated ids of the languages where the snippet is applicable in the scope field. If scope - // is left empty or omitted, the snippet gets applied to all languages. The prefix is what is - // used to trigger the snippet and the body will be expanded and inserted. Possible variables are: - // $1, $2 for tab stops, $0 for the final cursor position, and ${1:label}, ${2:another} for placeholders. + // Place your DSCv3 workspace snippets here. Each snippet is defined under a snippet name and has a scope, prefix, body and + // description. Add comma separated ids of the languages where the snippet is applicable in the scope field. If scope + // is left empty or omitted, the snippet gets applied to all languages. The prefix is what is + // used to trigger the snippet and the body will be expanded and inserted. Possible variables are: + // $1, $2 for tab stops, $0 for the final cursor position, and ${1:label}, ${2:another} for placeholders. // Placeholders with the same ids are connected. "Configuration function template": { "scope": "markdown", @@ -140,7 +140,7 @@ " ", "" ] - } + }, "Changelog Entry Multi Item": { "scope": "markdown", "prefix": "docs-changelog-entry-multi-issue-pr", @@ -158,7 +158,7 @@ " ", "" ] - } + }, "Changelog release heading": { "scope": "markdown", "prefix": "docs-changelog-release-heading", @@ -173,8 +173,7 @@ "[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\"", "[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}}" ] - - } + }, "Github Work Item Link": { "scope": "markdown", "prefix": "docs-gh-link", @@ -182,5 +181,14 @@ "body": [ "[#${1:work item id}]: https://github.com/PowerShell/DSC/issues/${1:work item id}" ] - } + }, + "RFC table entry": { + "scope": "markdown", + "prefix": "rfc-table-entry", + "description": "Template for an entry in the RFC History table", + "body": [ + "| RFC${1:NNNN} | ${2:Title} | ${3|Accepted,Rejected,Final|} | ${4:#123} |" + ] + }, + } diff --git a/rfc/RFC0000-rfc-process.md b/rfc/RFC0000-rfc-process.md new file mode 100644 index 000000000..7319ef7f7 --- /dev/null +++ b/rfc/RFC0000-rfc-process.md @@ -0,0 +1,213 @@ +--- +RFC: RFC0000 +Author: @michaeltlombardi +Sponsor: @michaeltlombardi +Status: Draft +SupercededBy: null +Version: 1.0 +Area: Process +CommentsDue: 2025-07-06 +--- + +# DSC RFC Process and Guidelines + +A DSC RFC (Request for Comments) is a publication to propose design changes and improvements to +DSC. This provides the community an opportunity to provide feedback before code is written where it +becomes harder to change at the risk of compatibility. + +This process was adapted from the [PowerShell RFC process][01]. + +## Roles + +- **Author**: All members of the community are allowed to author new RFCs and can provide feedback + to any RFC. +- **Working Group (WG)**: A group responsible for deciding whether or not an issue in the + repository requires a proposal and for providing feedback within an RFC proposal and votes to + accept or reject an RFC. + + For more information about Working Groups, see [Working Groups][02]. +- **Sponsor**: A person who commits to implementing an RFC if the WG accepts it. The sponsor may be + the Author, a WG member, or any member of the community. The WG won't accept an RFC proposal + without a Sponsor. + +## When to submit an RFC + +Generally, you should submit proposals as [issues in the DSC repository][03]. When reviewing +issues, the WG may request an RFC. The issue author, a WG member, or any other memberof the +community may then draft and submit an RFC for the issue. + +WG members may also submit an RFC for proposals arising from WG discussions, knowing that the +proposal is complex enough to warrant a full RFC. + +## Submitting an RFC + +When submitting an RFC, the Author shall: + +- Create a file named `RFCNNNN-.md` in the `rfc/drafts` folder. + + The Author _shall not_ assign the RFC number. The author shall leave the `NNNN` in the + filename. Example: `RFCNNNN-docs-extension.md` + + The file must use the [RFC template][04]. The Author must fill out the following fields in the + template frontmatter: + + - `Author` - Set to your GitHub username prefixed with `@`, like `@MyUserName`. + - `Status` - Set to `Draft`. + - `Version` - Set to `1.0`. + - `CommentsDue` - Set to a date at least one month from the date you intend to submit the PR. Use + [ISO8601][05] format, like `2022-09-27` for September 27, 2022. + + Set the `Sponsor` field to your GitHub username if you're willing to implement the RFC, assuming + the WG accepts it. + + Define the H1 title. Fill out each section of the template as directed by the template comments. +- Include any additional files, such as code samples, in the `rfc/draft/RFCNNNN/` folder. +- Check `Allow edits from maintainers` option when submitting the PR so that the WG can add the RFC + number to the draft, update the title, and fix the filename. +- Submit the PR as a [draft PR][06]. +- Use the prefix `RFC:` for the PR title. + +## Sponsoring an RFC + +At any time while the RFC is in the [Draft](#draft) or [Reviewing](#reviewing) state, the Author, a +WG member, or community member may choose to sponsor the RFC by committing to implement it, if +accepted. + +When a Sponsor commits to the RFC, a WG member will: + +1. Apply the `RFC - Sponsored` label to the PR. +1. Assign the PR to the Sponsor. +1. Set the `Sponsor` field of the draft RFC to the GitHub username of the Sponsor. + +The WG will only accept RFCs with a Sponsor. + +## Commenting on an RFC + +When providing feedback or otherwise commenting on an RFC proposal, focus your feedback and +discussion on the proposed experience and functionality. The WG may close conversations that are +distracting from the core purpose of the RFC, such as bikeshedding around names for proposed APIs. + +As always, you must adhere to the [Code of Conduct][coc] when participating in discussions in the +DSC repository. + +[coc]: ../CODE_OF_CONDUCT.md + +## RFC Status + +An RFC may be in any of the following states: + +- [Draft](#draft) +- [Reviewing](#reviewing) +- [Accepted](#accepted) +- [Experimental](#experimental) +- [Rejected](#rejected) +- [Withdrawn](#withdrawn) +- [Final](#final) + +### Draft + +When an RFC is initially submitted as a draft PR, it's in the `Draft` state. RFCs remain in this +state until the Author marks the PR as ready for review. + +While an RFC is in this state, we encourage contributors and WG members to read, discuss, and +comment on the RFC. Discussion and iteration during the drafting stage provides information and +context for the WG during the reviewing stage. + +After one month, the Author may mark their PR as ready for formal review, taking it out of draft. A +WG member will then apply the `RFC - Reviewing` label to the PR. + +### Reviewing + +After the author marks their PR as ready for review, the RFC moves into the formal review state. + +While the RFC is in review, the WG members are responsible for providing comments and feedback on +the PR. The WG meets at least once a month, during which they will review open RFCs. The WG will +always indicate to the Author a date by which the Author can expect feedback. The WG is responsible +for communicating with the Author during the review process to negotiate timelines for addressing +feedback and for updating the Author on the review status of their proposal. + +The RFC remains in this state until one of the following conditions is met: + +- The WG decides to reject the RFC, changing the state to [Rejected](#rejected). +- The RFC has a [Sponsor](#sponsoring-an-rfc) and the WG requests an experimental implementation, + changing the state to [Experimental](#experimental). +- The RFC has a [Sponsor](#sponsoring-an-rfc) and the WG decides to accept the RFC as-is, changing + the state to [Accepted](#accepted). +- The Author decides to withdraw their RFC, changing the state to [Withdrawn](#withdrawn). + +### Rejected + +If the WG decides not to proceed with the RFC, a WG member shall: + +1. Add a comment to the PR indicating the rationale for rejecting the RFC. +1. Add the `RFC - Rejected` label to denote that the WG rejected the RFC. +1. Close the PR instead of merging it. +1. Update the [RFC History][07] table to reflect the changed status. + +In the future, this can be done automatically with GitHub Actions. + +### Experimental + +Experimental implementations are used to provide a working example of proposed designs in order for +the WG and other users to understand real-world usage of the proposal. + +If the WG decides to request an experimental implementation, a WG member shall: + +1. Ensure the `Status` in the frontmatter of the RFC document is set to `Experimental`. +1. Apply the label `RFC - Experimental` to the PR. +1. Update the [RFC History][07] table to reflect the changed status. +1. Merge the PR. + +The Author may be asked to continue to update the RFC as the usage of the experimental feature +drives new insight into how the feature should be designed. + +When the WG is satisfied with the experimental implementation, a WG member will start +the process to finalize the RFC, moving it into the [Final](#final) state. + +### Accepted + +If the WG decides to accept the proposal as-is without requesting an experimental +implementation, a WG member shall: + +1. Ensure the `Status` in the frontmatter of the RFC document is set to `Accepted`. +1. Apply the label `RFC - Accepted` to the PR. +1. Update the [RFC History][07] table to reflect the changed status. +1. Merge the PR. + +When the WG is satisfied with the implementation, a WG member will start the process +to finalize the RFC, moving it into the [Final](#final) state. + +### Withdrawn + +If an Author decides to withdraw their RFC, either the Author or a WG member shall close the +PR without merging it. + +A WG member shall apply the `RFC - Withdrawn` label to the PR, indicating that the author +withdrew the RFC. + +### Final + +When the WG is satisfied with the implementation for an RFC, a WG member will begin +the process to finalize the RFC. + +To finalize an RFC, a WG member shall submit a PR which: + +1. Ensures the `Status` in the frontmatter of the RFC document is set to `Final`. +1. Move the RFC document from the `rfc/draft` folder to `rfc/final`. +1. Update the [RFC History][07] table to reflect the changed status. + +Any proposed changes should be made through a new RFC or as an issue in the +[PowerShell/DSC repository][08]. New RFCs should reference old RFCs where applicable. + +## History + +v1.0 - Initial draft. + +[01]:https://github.com/PowerShell/PowerShell-RFC/blob/master/RFC0000-RFC-Process.md +[02]: https://github.com/PowerShell/PowerShell/blob/master/docs/community/working-group.md +[03]: https://github.com/PowerShell/DSC/issues/new/choose +[04]: RFCNNNN-New-RFC-Template.md +[05]: 2022-09-27 +[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 +[07]: readme.md#rfc-history +[08]: https://github.com/powershell/dsc diff --git a/rfc/RFCNNNN-New-RFC-Template.md b/rfc/RFCNNNN-New-RFC-Template.md new file mode 100644 index 000000000..a75ab3b62 --- /dev/null +++ b/rfc/RFCNNNN-New-RFC-Template.md @@ -0,0 +1,73 @@ +--- +RFC: RFCNNNN # WG will set the number after submission +Author: null # <@GitHubUserName> +Sponsor: null # <@GitHubUserName> +Status: Draft # <Draft | Experimental | Accepted | Final> +SupercededBy: null # <Superceding RFC Number> +Version: 1.0 # <Major>.<Minor> +Area: null # <Area within the DSC project> +CommentsDue: null # <Date for submitting comments to current draft (minimum 1 month)> +--- + +# Title + +<!-- + Write a summary of your proposal in this section. Make sure to change the title to reflect + your proposal. +--> + +## Motivation + +<!-- + Indicate the value of the proposal in this section. Start with a brief user story following + this template: + + > As a <persona>, + > I want <functionality>, + > so that <benefit>. + + Replace the terms at the end of each line: + + - <persona> should clarify _who_ the proposal primarily benefits. + - <functionality> should indicate what effective change the proposal represents. + - <benefit> should include one or more ways the proposal improves the experience for the + <persona>. + + You can define more than one user story. + + After the user story, you may provide additional context expanding on the proposal. +--> + +## Proposed experience + +<!-- + Demonstrate an example of how the RFC will affect user or developer experience in this + section. Include examples of input and output. +--> + +## Specification + +<!-- + Define as specifically as possible your proposal with the technical requirements in this + section. If possible, include relevant JSON Schemas for proposed changes to data types, input, + and output. +--> + +## Alternate Proposals and Considerations + +<!-- + Include any alternate proposals and notes for the RFC in this section. +--> + +## Related work items + +<!-- + Include any relevant GitHub issues, discussions, and pull requests as unordered list items + in this section. If the work item title doesn't clearly indicate how it relates to this + RFC, add a short summary statement after the work item. + + For example: + + - #123 - Indicates the need for and prior conversation around discovering DSC resources from + remote registries. +--> diff --git a/rfc/draft/.gitkeep b/rfc/draft/.gitkeep new file mode 100644 index 000000000..e69de29bb diff --git a/rfc/final/.gitkeep b/rfc/final/.gitkeep new file mode 100644 index 000000000..e69de29bb diff --git a/rfc/readme.md b/rfc/readme.md new file mode 100644 index 000000000..c8963c60c --- /dev/null +++ b/rfc/readme.md @@ -0,0 +1,34 @@ +# Desired State Configuration RFC + +This folder contains RFC documents for community feedback on proposed changes and improvements + +See [RFC0000: RFC-Process][01] for process information. + +Along with making DSC open source, we're also inviting the community to author RFCs on proposed +design changes (instead of having long threads in issues). The DSC team will meet at least once per +month (more frequently, depending on amount of feedback) to review and respond. + +We'll continue to refine this process as we learn from it. + +## RFC History + +The following table shows the RFCs that have been reviewed and processed by the committee. It +doesn't include draft RFCs. + +<!-- + After an RFC PR is merged or closed, a maintainer should update this table to include a new + entry for the RFC. You can use the `rfc-table-entry` snippet in VS Code to create the new + entry. + + Use the pull requests column to link to the associated PR for the RFC. You can use the autolink + functionality and reference the pull request by number, like `#123`. + + For RFCs in the accepted, experimental, or final state, update the entry in the RFC column to + point to the merged document. +--> + +| RFC | Title | Status | Pull Requests | +|:-------:|:-------------------------------|:------:|:--------------| +| RFC0000 | DSC RFC Process and Guidelines | Draft | #868 | + +[01]: RFC0000-rfc-process.md