The SDL maintainers and stakeholders seek the help of the community to help guide and shape how SDL changes. To do that effectively, we outline in this document a process for introducing ideas to SDL and how the SDL maintainers will guide those ideas through the review process.
Any changes to the SDL RPC spec, the SDL protocol, public API changes to the SDL iOS or Android SDKs, or major changes to SDL Core must go through the SDL evolution proposal and review process. SDL is versioned using semantic versioning. Therefore, any public API removal, alteration, or addition is a minor or major version change to the respective spec or library, no matter how small the change. The only minor or major change that does not need to go through this process is a misspelled API name in a mobile SDK. In that case, write an issue against the respective repository. Changes that do not make a spec or public API change should go through the normal contribution process, for example, this is the iOS repository's process.
Everyone is welcome to discuss and propose new changes to SDL on the #sdl_evolution channel on the SDL slack. Proposals under current review will be given an issue on the sdl_evolution repository. Before posting a review, please read "What goes into a review?" below.
The SDL maintainers and stakeholders are currently responsible for the strategic direction of SDL and will have the final say on the result of a proposal. A rationale will always be posted along with the result of the review of a proposal.
The goal of the review process is to improve the proposal under review through constructive criticism and, eventually, determine the direction of SDL. When writing your review, here are some questions you might want to answer in your review:
- What is your evaluation of the proposal?
- Is the problem being addressed significant enough to warrant a change to SDL?
- Does this proposal fit well with the feel and direction of SDL?
- If you have used competitors with a similar feature, how do you feel that this proposal compares to those?
- How much effort did you put into your review? A glance, a quick reading, or an in-depth study?
Please state explicitly whether you believe that the proposal should be accepted into SDL.
A review should be written as a comment on the Github issue of the proposal created by the review manager.
- Check prior proposals: many ideas come up frequently, and may either be in active discussion on the mailing list, or may have been discussed already and have joined the Commonly Rejected Proposals list. Please check the issue archive and this list for context before proposing something new.
- Socialize the idea: propose a rough sketch of the idea on the #sdl_evolution channel of the SDL Slack, the problems it solves, what the solution looks like, etc., to gauge interest from the community.
- Develop the proposal: expand the rough sketch into a complete proposal, using the proposal template, and continue to refine the proposal on the evolution slack channel. Prototyping an implementation and its uses along with the proposal is encouraged, because it helps ensure both technical feasibility of the proposal as well as validating that the proposal solves the problems it is meant to solve.
- Request a review: initiate a pull request to the sdl_evolution repository to indicate to the maintainers that you would like the proposal to be reviewed. When the proposal is sufficiently detailed and clear, and addresses feedback from earlier discussions of the idea, the pull request will be accepted. The proposal will be assigned a proposal number as well as a maintainer to manage the review. In addition, an issue will be opened specifically for the review and attached to the proposal.
- Address feedback: in general, and especially during the review period, be responsive to questions and feedback about the proposal.
The review process for a particular proposal begins when the review team decides to accept a pull request of a new or updated proposal into the sdl_evolution repository. The proposal is assigned a proposal number (if it is a new proposal), then enters the review queue.
The review team will work with the author to assess when the proposal is ready for review. Reviews usually last a single week, but can run longer for particularly large or complex proposals.
When the scheduled review period arrives, the review manager will post the proposal to the #sdl_evolution slack channel, the #sdl_evolution_report slack channel, the SDL mailing list, and create a Github issue for the actual review, which will additionally be attached to the proposal. They will have the subject "[Review]" followed by the proposal title. The Review Manager will be responsible for tracking the status of the proposal in the proposal XML document. All feedback on the proposal should be addressed in the associated Github issue or to the review manager directly via email or Slack. To avoid delays, it is important that the proposal authors be available to answer questions, address feedback, and clarify their intent during the review period.
After the review has completed, the maintainers and stakeholders will make a decision on the proposal. The review manager is responsible for determining consensus among the maintainers and stakeholders, then reporting their decision to the proposal authors and SDL users. The review manager will update the proposal's state in the sdl_evolution repository to reflect that decision, then close and lock the related issue. Possible decisions include: Accepted, Rejected, Returned for Revision, and Deferred.
When a proposal enters review, an email using the following template will be sent to the #sdl_evolution slack channel, the #sdl_evolution_report channel, the SDL mailing list, and to a Github issue:
Hello SDL community,
The review of "<<PROPOSAL NAME>>" begins now and runs through <<REVIEW END DATE>>. The proposal is available here:
https://github.com/smartdevicelink/sdl_evolution/blob/master/proposals/NNNN-proposal.md
Reviews are an important part of the SDL evolution process. All reviews should be sent to the associated Github issue at:
https://github.com/smartdevicelink/sdl_evolution/issues/NNNN_proposal_name/
or, if you would like to keep your feedback private, directly to the review manager via slack or email:
Slack: https://smartdevicelink.slack.com/messages/@[REVIEWER_HANDLE]/
Email: maintainer-email@email.com
You may sign up for the SDL slack at this link:
The goal of the review process is to improve the proposal under review through constructive criticism and, eventually, determine the direction of SDL. When writing your review, here are some questions you might want to answer in your review:
- Is the problem being addressed significant enough to warrant a change to SDL?
- Does this proposal fit well with the feel and direction of SDL?
- If you have used competitors with a similar feature, how do you feel that this proposal compares to those?
- How much effort did you put into your review? A glance, a quick reading, or an in-depth study?
Please state explicitly whether you believe that the proposal should be accepted into SDL.
More information about the SDL evolution process is available at:
https://github.com/smartdevicelink/sdl_evolution/blob/master/process.md
The current status of all past and present evolution proposals is available at:
Thank you,
-<<REVIEW MANAGER NAME>>
Review Manager