Repository files navigation

In 2019 we decided to create a community process to discuss and reviewSalt Enhancements. Unfortunately I feel that this process has not provento be an effective way to solve the core issues around Salt Enhancements.Overall the Salt enhancement process has proven itself to be more of aburden than an accelerant to Salt stability, security, and progress.As such, I feel that the current optimal course of action is to shutthe process down.

Instead of the Salt Enhancement Proposal process we will add a timein the Open Hour for people to present ideas and concepts to betterunderstand if they are worth their effort to develop. Extensivedocumentation around more intrusive or involved enhancements shouldbe included in PRs.

By migrating the conversation into the PR process we ensure thatwe are only reviewing viable proposals instead of being burdenedwith requests that the core team is expected to fulfill.

Conversations about enhancements can also be held in the discussionstab in GitHub.

Effective immediately (01/24/2024) we will be archiving and freezingthe SEP repo.

-Thomas S Hatch, creator and founder of Salt Project

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

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

The "SEP" (Salt Enhancement Proposal) process is intended to provide aconsistent and controlled path for new features to enter the project.

This process is beingactively developed, and it will still change as morefeatures are implemented and the community settles on specific approaches tofeature development.

You should consider using this process if you intend to make "substantial"changes to Salt or its documentation. Some examples that would benefit from anSEP 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 SEP process is a great opportunity to get more eyeballs on your proposalbefore it becomes a part of a released version of Salt. Quite often, evenproposals that seem "obvious" can be significantly improved once a wider groupof interested people have a chance to weigh in.

The SEP process can also be helpful to encourage discussions about a proposedfeature as it is being designed, and incorporate important constraints into thedesign while it's easier to change, before the design has been fullyimplemented.

Changes that doNOT require an SEP:

• Rephrasing, reorganizing or refactoring
• Bug fixes
• Addition or removal of warnings
• Additions only likely to benoticed by other implementors-of-Salt,invisible to users-of-Salt.

In short, to get a major feature added to Salt, one must submit the SEP viapull-request. After a comment period, the SEP will be eitherAccepted orRejected. AnAccepted SEP may then be implemented with the goal ofeventual inclusion into Salt.

The following is a more detailed explanation of the process.

The SEP is proposed by submitting a pull request to this repo, by copying0000-template.md and modifying it. If the SEP pertains to any open issues,reference them in theSalt Issue(s) entry.

When copying the file, donot assign it a number. Simply name the file with ashort description of the SEP (e.g.subspace-transport.md). Once the pullrequest has been opened, a SaltStack core engineer will assign the SEP a numberand the SEP will enter the initialDraft status. At this time, thefollowing changes can be made to the SEP file:

1. Add the pull request number to theSEP PR entry at the top of the file
2. Rename the file to include the assigned SEP number, then commit and push toupdate the pull request

   $ git mv subspace-transport.md 0123-subspace-transport.md$ git commit -am'Assigned SEP number'$ git push origin branchname

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

Once the initial comment period has ended, the SEP will enterFinal Commentstatus. One (1) week will be allowed for any further comments. At the end oftheFinal Comment period, a decision will be made on whether or not toaccept the SEP. Acceptance requires approval from five (5) members of the coredevelopment team. As project creator,ThomasHatch will have a final veto on any SEP.

Additionally, asdiscussed, SaltStack will be publishing a SEP to form a Community Advisory Board (CAB).

At the end of theFinal Comment stage, the SEP will be eitherAcceptedorRejected. Either way, the pull request will be merged.

Note that acceptance does not mean that the feature will be immediatelyimplemented, or that it will be implemented at all; It merely means that thecore development team has agreed to it in principle. Additionally, the factthat an SEP pull request has been merged does not necessarily mean that the SEPhas been accepted; pull requests for rejected SEPs are merged so that they arevisible to others who might otherwise open an SEP for a previously-rejectedtopic.

AnAccepted SEP may proceed to be implemented. If no issues on the Saltissue tracker are listed underSalt Issue(s), then create one and open apull request to update the SEP with the issue number. All SEPs which havereached the implementation step must have at least one associated issue.

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

The SEP author (like any other developer) is welcome to post an implementationfor review after the SEP has been accepted. However, the author of an SEP isnot obligated to implement it. If the author has no plans to implement the SEP,they can indicate on their SEP that the implementation should be consideredUp for Grabs. Alternatively, if no apparent activity has occurred on theSEP for two (2) weeks, it will be consideredUp for Grabs.

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

The below statuses were discussed above:

• Draft: The initial status, from submission through the initial discussionperiod
• Final Comment: A one-week period after the initial comment period hasended
• Accepted: The SEP has been approved for future implementation
• Rejected: The SEP has been rejected during discussion phase
• Abandoned: The SEP is fundamentally good idea, but discussion andprogress have stagnated for any number of reasons. Progress may be resumed bythe original author, or the SEP re-started by a new SEP champion.

In additon, SEPs can be assigned the following statuses:

• Withdrawn: The SEP has been voluntarily withdrawn from consideration.stagnated,
• Up for Grabs: The SEP has been accepted, but nobody is actively workingtowards its implmentation.
• Implemented: The accepted SEP has been implemented.
• Obsolete: The accepted SEP is no longer relevant due to other changes inSalt, but should be considered for re-evaluation. The re-evaluation will bedone in a separate SEP. Once the new SEP is opened, theObsolete SEP willbe consideredReplaced.
• Replaced: The SEP has been superseded by another SEP.

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

1. In theStatus entry at the top of the SEP file
2. Via GitHub labels applied to the SEP's pull request

The following diagram may help with the potential paths a SEP may take.

SaltStack staff will post information about open SEPs to the#sep channelin the community Slack, as well as our community IRC and mailing list on aregular basis to encourage discussion.

This SEP process owes its inspiration to theReact RFC process,Yarn RFCprocess,Rust RFC process, andEmber RFC process.