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

Commit d1e29f6

Browse files
waynewwaynew
committed
Merge branch 'master' of github.com:terminalmage/salt-rfc into erik-master
Incorporated changes from #1 (comment)
2 parents 7b49864 + 22560f0 commit d1e29f6

File tree

2 files changed

+203
-1
lines changed

2 files changed

+203
-1
lines changed

‎0000-template.md‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
- Feature Name: (fill with a unique identifier, ex: my-awesome-feature)
2+
- Start Date: (fill with today's date, YYYY-MM-DD)
3+
- SEP Status: Draft
4+
- SEP PR: (leave this empty)
5+
- Salt Issue: (leave this empty)
6+
7+
# Summary
8+
[summary]: #summary
9+
10+
Brief explanation of the feature.
11+
12+
# Motivation
13+
[motivation]: #motivation
14+
15+
Why are we doing this? What use cases does it support? What is the expected outcome?
16+
17+
If this SEP 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.
18+
19+
# Design
20+
[design]: #detailed-design
21+
22+
This is the bulk of the SEP. Explain the design in enough detail for somebody familiar
23+
with the product to understand, and for somebody familiar with the internals to implement. It should include:
24+
25+
- Definition of any new terminology
26+
- Examples of how the feature is used.
27+
- Corner-cases
28+
- A basic code example in case the proposal involves a new or changed API
29+
- Outline of a test plan for this feature. How do you plan to test it? Can it be automated?
30+
31+
## Alternatives
32+
[alternatives]: #alternatives
33+
34+
What other designs have been considered? What is the impact of not doing this?
35+
36+
## Unresolved questions
37+
[unresolved]: #unresolved-questions
38+
39+
What parts of the design are still TBD?
40+
41+
# Drawbacks
42+
[drawbacks]: #drawbacks
43+
44+
Why should we *not* do this? Please consider:
45+
46+
- Implementation cost, both in term of code size and complexity
47+
- Integration of this feature with other existing and planned features
48+
- Cost of migrating existing Salt setups (is it a breaking change?)
49+
- Documentation (would Salt documentation need to be re-organized or altered?)
50+
51+
52+
There are tradeoffs to choosing any path. Attempt to identify them here.

‎README.md‎

Lines changed: 151 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,153 @@
11
# Salt Enhancement Proposals
22

3-
Proposals to Enhance Salt
3+
Many changes, including bug fixes and documentation improvements, can be
4+
implemented and reviewed via the normal GitHub pull request workflow.
5+
6+
Some changes though are "substantial", and we ask that these be put through a
7+
bit of a design process and produce a consensus among the Salt core team.
8+
9+
The "SEP" (Salt Enhancement Proposal) process is intended to provide a
10+
consistent and controlled path for new features to enter the project.
11+
12+
This process is being **actively developed**, and it will still change as more
13+
features are implemented and the community settles on specific approaches to
14+
feature development.
15+
16+
## When to follow this process
17+
18+
You should consider using this process if you intend to make "substantial"
19+
changes to Salt or its documentation. Some examples that would benefit from an
20+
SEP are:
21+
22+
- A new feature that creates new API surface area
23+
- The removal of features that already shipped
24+
- The introduction of new idiomatic usage or conventions
25+
26+
The SEP process is a great opportunity to get more eyeballs on your proposal
27+
before it becomes a part of a released version of Salt. Quite often, even
28+
proposals that seem "obvious" can be significantly improved once a wider group
29+
of interested people have a chance to weigh in.
30+
31+
The SEP process can also be helpful to encourage discussions about a proposed
32+
feature as it is being designed, and incorporate important constraints into the
33+
design while it's easier to change, before the design has been fully
34+
implemented.
35+
36+
Changes that do **NOT** require an SEP:
37+
38+
- Rephrasing, reorganizing or refactoring
39+
- Bug fixes
40+
- Addition or removal of warnings
41+
- Additions only likely to be _noticed by_ other implementors-of-Salt,
42+
invisible to users-of-Salt.
43+
44+
## What the process is
45+
46+
In short, to get a major feature added to Salt, one must submit the SEP via
47+
pull-request. After a comment period, the SEP will be either **Accepted** or
48+
**Rejected**. An **Accepted** SEP may then be implemented with the goal of
49+
eventual inclusion into Salt.
50+
51+
## The SEP life-cycle
52+
The following is a more detailed explanation of the process.
53+
54+
### 1. Proposal
55+
The SEP is proposed by submitting a pull request to this repo, by copying
56+
`0000-template.md` and modifying it. If the SEP pertains to any open issues,
57+
reference them in the **Salt Issue(s)** entry.
58+
59+
When copying the file, do _not_ assign it a number. Simply name the file with a
60+
short description of the SEP (e.g. `subspace-transport.md`). Once the pull
61+
request has been opened, a SaltStack core engineer will assign the SEP a number
62+
and the SEP will enter the initial **Draft** status. At this time, the
63+
following changes can be made to the SEP file:
64+
65+
1. Add the pull request number to the **SEP PR** entry at the top of the file
66+
2. Rename the file to include the assigned SEP number, then commit and push to
67+
update the pull request
68+
```bash
69+
$ git mv subspace-transport.md 0123-subspace-transport.md
70+
$ git commit -am 'Assigned SEP number'
71+
$ git push origin branchname
72+
```
73+
74+
### 2. Discussion
75+
The pull request will remain open and serve as the comment thread for the SEP.
76+
The initial comment period will last no fewer than two (2) weeks, and may be
77+
extended as deemed necessary based on comment activity.
78+
79+
Once the initial comment period has ended, the SEP will enter **Final Comment**
80+
status. One (1) week will be allowed for any further comments. At the end of
81+
the **Final Comment** period, a decision will be made on whether or not to
82+
accept the SEP. Acceptance requires approval from five (5) members of the core
83+
development team. As project creator, [Thomas
84+
Hatch](https://github.com/thatch45) will have a final veto on any SEP.
85+
86+
Additionally, as
87+
[discussed](https://github.com/saltstack/salt-enhancement-proposals/pull/1#issuecomment-468823572), SaltStack will be publishing a SEP to form a Community Advisory Board (CAB).
88+
89+
### 3. Acceptance / Rejection
90+
At the end of the **Final Comment** stage, the SEP will be either **Accepted**
91+
or **Rejected**. Either way, the pull request will be merged.
92+
93+
Note that acceptance does not mean that the feature will be immediately
94+
implemented, or that it will be implemented at all; It merely means that the
95+
core development team has agreed to it in principle. Additionally, the fact
96+
that an SEP pull request has been merged does not necessarily mean that the SEP
97+
has been accepted; pull requests for rejected SEPs are merged so that they are
98+
visible to others who might otherwise open an SEP for a previously-rejected
99+
topic.
100+
101+
### 4. Implementation
102+
An **Accepted** SEP may proceed to be implemented. If no issues on the Salt
103+
issue tracker are listed under **Salt Issue(s)**, then create one and open a
104+
pull request to update the SEP with the issue number. All SEPs which have
105+
reached the implementation step must have at least one associated issue.
106+
107+
We should strive to write each SEP in a way that it will reflect the final
108+
design of the feature; However, if during implementation things change, the SEP
109+
document should be updated accordingly.
110+
111+
The SEP author (like any other developer) is welcome to post an implementation
112+
for review after the SEP has been accepted. However, the author of an SEP is
113+
not obligated to implement it.
114+
115+
If you are interested in working on the implementation for an accepted SEP, but
116+
cannot determine if someone else is already working on it, feel free to ask
117+
(e.g. by leaving a comment on the associated issue).
118+
119+
## Summary of SEP Statuses
120+
The below statuses were discussed above:
121+
- **Draft**: The initial status, from submission through the initial discussion
122+
period
123+
- **Final Comment**: A one-week period after the initial comment period has
124+
ended
125+
- **Accepted**: The SEP has been approved for future implementation
126+
- **Rejected**: The SEP has been rejected during discussion phase
127+
128+
In additon, SEPs can be assigned the following statuses:
129+
- **Withdrawn**: The SEP has been voluntarily withdrawn from consideration
130+
- **Implemented**: The accepted SEP has been implemented
131+
- **Obsolete**: The accepted SEP is no longer relevant due to other changes in
132+
Salt, but should be considered for re-evaluation. The re-evaluation will be
133+
done in a separate SEP. Once the new SEP is opened, the **Obsolete** SEP will
134+
be considered **Replaced**.
135+
- **Replaced**: The SEP has been superseded by another SEP
136+
137+
The SEP's status can be viewed in two ways:
138+
139+
1. In the **Status** entry at the top of the SEP file
140+
2. Via GitHub labels applied to the SEP's pull request
141+
142+
## Reviewing SEPs
143+
SaltStack staff will post information about open SEPs to the **#sep** channel
144+
in the community Slack, as well as our community IRC and mailing list on a
145+
regular basis to encourage discussion.
146+
147+
**This SEP process owes its inspiration to the [React RFC process], [Yarn RFC
148+
process], [Rust RFC process], and [Ember RFC process]**
149+
150+
[React RFC process]: https://github.com/reactjs/rfcs
151+
[Yarn RFC process]: https://github.com/yarnpkg/rfcs
152+
[Rust RFC process]: https://github.com/rust-lang/rfcs
153+
[Ember RFC process]: https://github.com/emberjs/rfcs

0 commit comments

Comments
 (0)