Skip to content
This repository has been archived by the owner on Jan 24, 2024. It is now read-only.

Establish RFC process #1

Merged
merged 1 commit into from
Mar 5, 2019
Merged

Establish RFC process #1

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
52 changes: 52 additions & 0 deletions 0000-template.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,52 @@
- Feature Name: (fill with a unique identifier, ex: my-awesome-feature)
- Start Date: (fill with today's date, YYYY-MM-DD)
- RFC Status: Draft
- RFC PR: (leave this empty)
- Salt Issue: (leave this empty)

# Summary
[summary]: #summary

Brief explanation of the feature.

# Motivation
[motivation]: #motivation

Why are we doing this? What use cases does it support? What is the expected outcome?

If this RFC is not accepted, the motivation could be used to develop alternative solutions. Enumerate the constraints you are trying to solve without coupling them too closely to the solution you have in mind.

# Design
[design]: #detailed-design

This is the bulk of the RFC. Explain the design in enough detail for somebody familiar
with the product to understand, and for somebody familiar with the internals to implement. It should include:

- Definition of any new terminology
- Examples of how the feature is used.
- Corner-cases
- A basic code example in case the proposal involves a new or changed API
- Outline of a test plan for this feature. How do you plan to test it? Can it be automated?

## Alternatives
[alternatives]: #alternatives

What other designs have been considered? What is the impact of not doing this?

## Unresolved questions
[unresolved]: #unresolved-questions

What parts of the design are still TBD?

# Drawbacks
[drawbacks]: #drawbacks

Why should we *not* do this? Please consider:

- Implementation cost, both in term of code size and complexity
- Integration of this feature with other existing and planned features
- Cost of migrating existing Salt setups (is it a breaking change?)
- Documentation (would Salt documentation need to be re-organized or altered?)


There are tradeoffs to choosing any path. Attempt to identify them here.
153 changes: 151 additions & 2 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,2 +1,151 @@
# salt-rfc
Request For Comments
# Salt RFCs

Many changes, including bug fixes and documentation improvements, can be
implemented and reviewed via the normal GitHub pull request workflow.

Some changes though are "substantial", and we ask that these be put through a
bit of a design process and produce a consensus among the Salt core team.

The "RFC" (request for comments) process is intended to provide a consistent
and controlled path for new features to enter the project.

This process is being **actively developed**, and it will still change as more
features are implemented and the community settles on specific approaches to
feature development.

## When to follow this process

You should consider using this process if you intend to make "substantial"
changes to Salt or its documentation. Some examples that would benefit from an
RFC are:

- A new feature that creates new API surface area
- The removal of features that already shipped
- The introduction of new idiomatic usage or conventions

The RFC process is a great opportunity to get more eyeballs on your proposal
before it becomes a part of a released version of Salt. Quite often, even
proposals that seem "obvious" can be significantly improved once a wider group
of interested people have a chance to weigh in.

The RFC process can also be helpful to encourage discussions about a proposed
feature as it is being designed, and incorporate important constraints into the
design while it's easier to change, before the design has been fully
implemented.

Changes that do **NOT** require an RFC:

- Rephrasing, reorganizing or refactoring
- Bug fixes
- Addition or removal of warnings
- Additions only likely to be _noticed by_ other implementors-of-Salt,
invisible to users-of-Salt.

## What the process is

In short, to get a major feature added to Salt, one must submit the RFC via
pull-request. After a comment period, the RFC will be either **Accepted** or
**Rejected**. An **Accepted** RFC may then be implemented with the goal of
eventual inclusion into Salt.

## The RFC life-cycle
The following is a more detailed explanation of the process.

### 1. Proposal
The RFC is proposed by submitting a pull request to this repo, by copying
`0000-template.md` and modifying it. If the RFC pertains to any open issues,
reference them in the **Salt Issue(s)** entry.

When copying the file, do _not_ assign it a number. Simply name the file with a
short description of the RFC (e.g. `subspace-transport.md`). Once the pull
request has been opened, a SaltStack core engineer will assign the RFC a number
and the RFC will enter the initial **Draft** status. At this time, the
following changes can be made to the RFC file:

1. Add the pull request number to the **RFC PR** entry at the top of the file
2. Rename the file to include the assigned RFC number, then commit and push to
update the pull request
```bash
$ git mv subspace-transport.md 0123-subspace-transport.md
$ git commit -am 'Assigned RFC number'
$ git push origin branchname
```

### 2. Discussion
The pull request will remain open and serve as the comment thread for the RFC.
The initial comment period will last no fewer than two (2) weeks, and may be
extended as deemed necessary based on comment activity.

Once the initial comment period has ended, the RFC will enter **Final Comment**
status. One (1) week will be allowed for any further comments. At the end of
the **Final Comment** period, a decision will be made on whether or not to
accept the RFC. Acceptance requires approval from five (5) members of the core
development team. As project creator, [Thomas
Hatch](https://github.com/thatch45) will have a final veto on any RFC.
Copy link

@gtmanfred gtmanfred Feb 14, 2019 •
edited
Loading

Choose a reason for hiding this comment

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

For the mechanics of the proposal, I would like to propose that we discuss an alternative to how RFCs get accepted.

In short, I think that much of what needs to be achieved here could easily be done so through the formation of an RFC Review Team that would consist of a balance of community members and Salt employees or customers. The community side could be elected through a process that ought not to be too hard to enact.

The team could meet every couple of weeks in an open meeting held via videoconference which is announced well in advance. Anybody not formally on the RFC Review Team who wishes to would be welcome to join would, of course, be welcome.

Agendas would typically be to review open RFCs and to provide comments and discussion. For RFCs ready for a vote, members could vote. The BDFL could, as discussed, veto any decision though this would likely be quite rare.

Meeting minutes and and video archives could be made available to those who could not attend.

Copy link
Contributor

Choose a reason for hiding this comment

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

I think I'd like to see the current proposal to through a couple of PRs before requiring a synchronous process.

Salt, being a world wide community, has interested parties across time zones.

As it is, discussion already can happen in the open on PRs - if we feel the need to summarize discussion points, that can happen on the PR. The only thing we might lose is the face-to-face nature of the teleconference.

I do prefer face-to-face interactions for some things (there's a reason there's a language summit during pycons), but I'm not sure if it's the best choice for typical RFCs.

Do you have some experience using video conferencing for reviews, or some other thoughts about why it would be better than the asynchronous style proposed?

Copy link
Contributor

Choose a reason for hiding this comment

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

Hi @waynew. I took a brief swing through some popular projects to find a couple of quick examples for you:

https://github.com/helm/helm
Developer Call: Thursdays at 9:30-10:00 Pacific. https://zoom.us/j/696660622

Jaeger tracing
https://www.jaegertracing.io/get-in-touch/#bi-weekly-project-meetings

Envoy:
https://github.com/envoyproxy/envoy#community-meeting

I honestly just grabbed three projects totally at random from the CNCF page but there are many others.


### 3. Acceptance / Rejection
Copy link

Choose a reason for hiding this comment

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

Should rejected RFCs be put into their own folder so that they aren't intermingled with other RFCs?

Copy link
Contributor

Choose a reason for hiding this comment

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

@DWSR We've discussed both sides of the coin. (also, rejected RFCs will be merged, so we can use them later to point to and say, "No, we're not doing that because it's already been proposed" - basically taking a page from the PEP process, rejected PEPs are still PEPs)

I believe we've talked about simply maintaining a .md file here in the repo with a list of "accepted" and "rejected" RFCs. Then one can see at a glance what RFCs even exist, just by scrolling through the file list here on GitHub. Even if we hit 1,000 RFCs, it still shouldn't be awful to scroll through.

What's your scenario scenario/thought behind sticking them in their own folder?

Copy link

Choose a reason for hiding this comment

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

Sticking rejected RFCs in their own folder makes them a little less visible than accepted RFCs, but maintaining a TOC is a good compromise, I think.

I would love to see a static site though

At the end of the **Final Comment** stage, the RFC will be either **Accepted**
or **Rejected**. Either way, the pull request will be merged.

Note that acceptance does not mean that the feature will be immediately
implemented, or that it will be implemented at all; It merely means that the
core development team has agreed to it in principle. Additionally, the fact
that an RFC pull request has been merged does not necessarily mean that the RFC
has been accepted; pull requests for rejected RFCs are merged so that they are
visible to others who might otherwise open an RFC for a previously-rejected
topic.

### 4. Implementation
An **Accepted** RFC may proceed to be implemented. If no issues on the Salt
issue tracker are listed under **Salt Issue(s)**, then create one and open a
pull request to update the RFC with the issue number. All RFCs which have
reached the implementation step must have at least one associated issue.

We should strive to write each RFC in a way that it will reflect the final
design of the feature; However, if during implementation things change, the RFC
document should be updated accordingly.

The RFC author (like any other developer) is welcome to post an implementation
for review after the RFC has been accepted. However, the author of an RFC is
not obligated to implement it.

If you are interested in working on the implementation for an accepted RFC, but
cannot determine if someone else is already working on it, feel free to ask
(e.g. by leaving a comment on the associated issue).

## Summary of RFC Statuses
The below statuses were discussed above:
- **Draft**: The initial status, from submission through the initial discussion
period
- **Final Comment**: A one-week period after the initial comment period has
ended
- **Accepted**: The RFC has been approved for future implementation
- **Rejected**: The RFC has been rejected during discussion phase

In additon, RFCs can be assigned the following statuses:
- **Withdrawn**: The RFC has been voluntarily withdrawn from consideration
- **Implemented**: The accepted RFC has been implemented
- **Obsolete**: The accepted RFC is no longer relevant due to other changes in
Salt, but should be considered for re-evaluation. The re-evaluation will be
done in a separate RFC. Once the new RFC is opened, the **Obsolete** RFC will
be considered **Replaced**.
- **Replaced**: The RFC has been superseded by another RFC

The RFC's status can be viewed in two ways:

1. In the **Status** entry at the top of the RFC file
2. Via GitHub labels applied to the RFC's pull request

## Reviewing RFCs
SaltStack staff will post information about open RFCs to the **#rfc** channel
in the community Slack, as well as our community IRC and mailing list on a
regular basis to encourage discussion.

**This RFC process owes its inspiration to the [React RFC process], [Yarn RFC
process], [Rust RFC process], and [Ember RFC process]**

[React RFC process]: https://github.com/reactjs/rfcs
[Yarn RFC process]: https://github.com/yarnpkg/rfcs
[Rust RFC process]: https://github.com/rust-lang/rfcs
[Ember RFC process]: https://github.com/emberjs/rfcs