Skip to content

first pass of RFC refactor #87

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Apr 20, 2017
Merged

first pass of RFC refactor #87

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
da75281
first pass of RFC refactor
Mar 31, 2017
c55700d
address RFC refactor comments
Apr 11, 2017
1e6500b
addressed last round of comments from Committee
Apr 13, 2017
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
88 changes: 44 additions & 44 deletions RFC0000-RFC-Process.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,9 +1,9 @@
---
RFC: RFC0000
Author: Steve Lee
Author: Steve Lee, Joey Aiello
Status: Draft
Area: Process
Version: 1.3.1
Version: 1.4
Feedback: https://github.com/PowerShell/PowerShell-Language-RFC/issues/5
---

Expand All @@ -14,7 +14,7 @@ This provides the community an opportunity to provide feedback before code is wr
compatibility.
The complete list of RFCs are available at https://github.com/powershell/powershell-rfc

This process was adapted from the Chef RFC process as well as from DMTF.org process.
This process was adapted from the Chef RFC process as well as from the DMTF.org process.

## Roles

Expand All @@ -23,25 +23,26 @@ This process was adapted from the Chef RFC process as well as from DMTF.org proc
(Learn more about the PowerShell Committee [here](https://github.com/PowerShell/PowerShell/blob/master/docs/community/governance.md#powershell-committee).)
* **Committee Member**: An individual member of the PowerShell Committee.

## RFC Naming Convention
## RFC Submission Convention

RFC documents shall follow the naming convention of "RFCNNNN-Title.md".
Authors of RFCs do not assign an RFC number.
When the Pull Request is submitted, ensure `Allow edits from maintainers` is checked so that the Committee can add the RFC number to the draft and also update the title accordingly.
* When submitted, RFC documents shall follow the naming convention of `RFCNNNN-<Title>.md`.
* Authors of RFCs shall not assign the RFC number (leave the `NNNN` in the filename).
* When the Pull Request is submitted, the author shall check `Allow edits from maintainers` so that the Committee can add the RFC number to the draft, update the title, and fix the filename.

## RFC Template

RFC documents shall follow the following template:

```markdown
---
RFC: RFC<four digit unique incrementing number - assigned by Committee>
RFC: RFC<four digit unique incrementing number assigned by Committee, this shall be left blank by the author>
Author: <First Last>
Status: <Draft | Experimental | Accepted | Rejected | Withdrawn | Final>
SupercededBy: <link to another RFC>
Version: <Major>.<Minor>
Area: <Area within the PowerShell language>
Comments Due: <Date for submitting comments to current draft (minimum 1 month)>
Plan to implement: <Yes | No>
---

# Title
Expand All @@ -62,59 +63,55 @@ Description and rationale.

## RFC Workflow

RFCs go through applicable stages:
RFCs may go through the following stages:

* Draft
### Draft

This is the initial draft of an RFC posted for comments and considered a work-in-progress.

This is the initial draft of a RFC posted for comments and considered a work-in-progress.
* New proposed drafts should be submitted as a Pull Request from the Author's fork into the `Draft-Accepted` folder.
* The Author shall ensure that the `Allow edits from maintainers` box is checked so that a Committee Member can assign the next RFC number.
* If the Pull Request has followed the correct template and process, a Committee Member will assign the label `Review - Open for comments` to the Pull Request to indicate that anyone can comment on the content of the submission.
Typically, one or two months is allowed for comments, though this may be extended if a submission is particularly contentious or hasn't received enough feedback for the Committee to feel comfortable making a decision.
* When the Committee closes the comment period, the Author should update the RFC and Pull Request with a new commit to address the comments.
* The Committee shall vote to merge or reject the RFC.
Note: the Comittee may be slower to respond to RFCs where the Author has indicated that they do not plan to implement the RFC.

New proposed drafts should be submitted as a Pull Request from the Author's fork.
The Author must ensure that 'Allow edits from maintainers' is checked so that a Committee Member can assign the next RFC number.
### Draft-Accepted

Committee Members also ensure that the RFC adheres to the template and the RFC process before merging the Pull Request.
The PowerShell Committee has reviewed the RFC and comments, and has voted to accept the RFC as a Draft.

After the Pull Request is merged, Maintainers will ask the Author to create an issue for this RFC to collect and respond to feedback on the RFC.
(The Author should create issue so that they get notified of new comments instead of the Committee Member.)
Typically, one or two months is allowed for comments (see `Comments Due` above).
* New comments are not being sought.
* No one has begun implementing the RFC, and there are no current plans to implement the RFC.
In this case, the Comittee will create `up-for-grabs` Issues in the [PowerShell](https://github.com/PowerShell/PowerShell) repository.

At this point, the community discusses the RFC.
### Experimental

After the `Comments Due` date, the Author summarizes the comments, submits a new Pull Request to make the final RFC Draft, and asks the PowerShell Committee to vote.
RFCs in the `Experimental` stage have been accepted by the Committee, and code is being written to provide a working example of the proposed design change to get additional feedback.

Just before voting, the PowerShell Comittee merges the Pull Request.
The PowerShell Committee then votes to accept or reject the RFC Draft.
### Experimental-Accepted

* Draft-Accepted

The PowerShell Committee has reviewed the RFC Draft and comments, and has voted to accept the RFC Draft.

At this point, new comments are not being sought.

No one has begun implementing the RFC, and there are no current plans to implement the RFC.

The community is invited to implement the RFC.

* Experimental

Comments have been reviewed and code is being written to provide an working example of the proposed design change to get further feedback.
Feedback from the experimental implementation and RFC have been reviewed.

* Experimental-Accepted
Because this working prototype already exists in preview builds available on GitHub, the community provide feedback on the implementation as issues in the [PowerShell/PowerShell repository](https://github.com/powershell/powershell)

Feedback from the experimental implementation and RFC have been reviewed.
Engineering team will work towards final implementation in code to match the RFC.
As the engineering team or code contributor works towards a final implementation, they should submit pull requests to PowerShell-RFC in order to keep the RFC in sync with the implementation.
These pull requests shall be reviewed and accepted by the Committee, but a formal vote is not necessary.
The Committee should merely confirm that the changes in the RFC match the working implementation.

* Rejected
### Rejected

Based on community feedback, this RFC was decided to not proceed any further.
RFCs in the `Rejected` state were rejected by the Committee who decided not to proceed further.

* Withdrawn
### Withdrawn

Author has decided not to pursue this RFC any further
RFCs in the `Withdrawn` state were rescinded by the RFC Author.

* Final
### Final

Design and implementation is considered complete.
Any proposed changes would be through a new RFC.
RFCs in the `Final` state are considered fully complete and implemented in PowerShell.
Any proposed changes should be made through a new RFC or via an Issue in the [PowerShell/PowerShell repository](https://github.com/powershell/powershell).
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Rather than an issue, why not a PR to modify the existing RFC?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't really want to get into the business of deciding what constitutes a "modification to an existing RFC" vs. "a fully new feature". It's a lot easier to just say "that's done now, next RFC".

I could be wrong here, though. Do you guys have experience with this on either side at Chef?

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah, for example, our RFC 062 - Exit Codes
Initial adoption of the RFC - chef-boneyard/chef-rfc#157
Modifications - chef-boneyard/chef-rfc#189
- chef-boneyard/chef-rfc#197
- chef-boneyard/chef-rfc#225

In large part it depends on how big of a change you are talking about. If you are substantially changing the behavior, I think a new RFC is warranted. If you are just extending existing behavior or clarifying the direction, a modification to the exiting RFC is sufficient.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Discussed this with the @PowerShell/powershell-committee, and we agree that once something is accepted into the Final state, it should remain unchanged. In the long run, it makes things simpler for us. If necessary, the new RFC should reference the old. (Ultimately, I think it's a positive if RFCs are shorter and easier to parse.)

If this becomes a problem later, we can always change our approach here.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

👌

New RFCs should reference old RFCs where applicable.

## History
v1.1 - 5-20-2016 - Updated to enable RFCs for design changes that don't require code changes.
Expand All @@ -125,3 +122,6 @@ v1.2 - 8-18-2016 - Open submitting RFCs to the community and update formatting.
v1.3 - 9-26-2016 - Added Withdrawn stage. Comments Due field to template. Updated guidance on RFC numbering.

v1.3.1 - 3-22-2017 - Cleaned up language and made explicit clarifications to process

v1.4 - 3-31-2017 - Revised the RFC process to leverage pull requests for comments instead of issues.
Continued cleanup of language and formatting.