Skip to content

Commit 5f59949

Browse files
heathermillerheathermiller
committed
1 parent d95343e commit 5f59949

File tree

1 file changed

+250
-38
lines changed

1 file changed

+250
-38
lines changed

‎sips/sip-submission.md

Lines changed: 250 additions & 38 deletions
Original file line numberDiff line numberDiff line change
@@ -1,61 +1,273 @@
11
---
22
layout: sip-landing
3-
title: SIP Submission Process
3+
title: SIP Specification and Submission
44
---
55

6-
## How do I get started? ##
6+
A **SIP** (_Scala Improvement Process_) is a process for submitting changes to
7+
the Scala language. Its main motivation is to become the primary mechanism to
8+
propose, discuss and implement language changes. In this process, all changes to
9+
the language go through design documents, called Scala Improvement Proposals
10+
(SIPs), which are openly discussed by a committee and only upon reaching a
11+
consensus are accepted to be merged into the Scala compiler.
712

8-
Before submitting a SIP, it is a good to float your proposal on [scala-debate](https://groups.google.com/forum/#!forum/scala-debate). Be specific and already draw up a document that contains all relevant details. Often, public discussions help to refine a proposal to a point where it can become a SIP.
13+
The aim of the Scala Improvement Process is to apply the openness and
14+
collaboration that have shaped Scala's documentation and implementation to the
15+
process of evolving the language. This document captures our guidelines,
16+
commitments and expectations regarding this process.
917

10-
## How do I submit? ##
18+
## Why write a SIP?
1119

12-
The process to submit is simple:
20+
SIPs are key to making Scala better for the good of everyone. If you decide to
21+
invest the time and effort of putting a SIP forward and seeing it through, your
22+
efforts and time will shape and improve the language, which means that your
23+
proposal may impact the life of a myriad of developers all over the world,
24+
including those on your own team. For many, this aspect alone can be quite
25+
worthwhile.
1326

14-
* Fork the Scala documentation repository, [http://github.com/scala/scala.github.com](http://github.com/scala/scala.github.com).
15-
* Create a new SIP file in the `sips/pending/_posts/`. Check the [Writing a SIP Tutorial](sip-tutorial.html)
16-
* Make sure the new file follows the format: `YYYY-MM-dd-{title}.md`. Use the proposal date for `YYYY-MM-dd`.
17-
* Use the [Markdown Syntax](http://daringfireball.net/projects/markdown/syntax) to write your SIP.
18-
* Follow the instructions in the [README](https://github.com/scala/scala.github.com/blob/gh-pages/README.md) to build your SIP locally so you can ensure that it looks correct on the website.
19-
* Create a link to your SIP in the "pending sips" section of `index.md`
20-
* Commit your changes to your forked repository
21-
* Create a new [pull request](https://github.com/scala/scala.github.com/pull/new/gh-pages). This will notify the Scala SIP team.
27+
However, it's important to note that seeing a SIP through to its conclusion is
28+
an involved task. On the one hand, it takes time to convince people that your
29+
suggestions are a worthwhile change for hundreds of thousands of developers to
30+
accept. Particularly given the sheer volume of developers that could be affected
31+
by your SIP, SIP acceptance is conservative and carefully thought through.
32+
Typically, this includes many rounds of discussion with core Scala maintainers
33+
and the overall community, several iterations on the design of the SIP, and some
34+
effort at prototyping the proposed change. Often, it takes months of discussion,
35+
re-design, and prototyping for a SIP to be accepted and included in the Scala
36+
compiler. It is, therefore important to note that seeing a SIP through to its
37+
conclusion can be time-consuming and not all SIPs may end up in the Scala
38+
compiler, although they may teach us all something!
39+
40+
If you’re motivated enough to go through this involved but rewarding process, go
41+
on with writing and keep on reading.
42+
43+
## What's the process for submitting a SIP?
44+
45+
There are four major steps in the SIP process:
46+
47+
1. Initial informal discussion (2 weeks)
48+
2. Submission
49+
3. Formal presentation (up to 1 month)
50+
4. Formal evaluation (up to 6 months)
51+
52+
### Initial informal discussion (2 weeks)
53+
54+
Before submitting a SIP, it is required that you perform necessary preparations:
55+
56+
1. Discuss your idea on the Scala mailing lists (currently, we suggest
57+
cross-posting on
58+
[scala-sips](https://groups.google.com/forum/#!forum/scala-sips),
59+
[scala-debate](https://groups.google.com/forum/#!forum/scala-debate), and
60+
[scala-internals](https://groups.google.com/forum/#!forum/scala-internals). This
61+
may change in the future.) Create a topic that starts with “Pre-SIP” and briefly
62+
describe what you would like to change and why you think it’s a good idea.
63+
64+
Proposing your ideas on the mailing list is not an optional step. For every
65+
change to the language, it is important to gauge interest from the compiler
66+
maintainers and the community. Use this step to promote your idea and gather
67+
early feedback on your informal proposal. It may happen that experts and
68+
community members may have tried something similar in the past and may offer
69+
valuable advice.
70+
71+
Within two weeks after your submission of the pre-SIP to the mailing list, the
72+
Process Lead will intervene and advise you whether your idea can be submitted as
73+
a SIP or needs more work.
74+
75+
76+
### Submission
77+
78+
After receiving the green light from the Process Lead, you can write up your
79+
idea and submit it as a SIP. It ought to contain a clear specification of the
80+
proposed changes. When such changes significantly alter the compiler internals,
81+
the author is invited to provide a proof of concept. Delivering a basic
82+
implementation can speed up the process dramatically. Even compiler hackers find
83+
very difficult to predict the interaction between the design and the
84+
implementation, so the sooner we have an evidence of a working prototype that
85+
interacts with all the features in Scala, the better. Otherwise, committee
86+
members may feel that the proposed changes are impossible and automatically
87+
dismiss them. If your changes are big or somewhat controversial, don’t let
88+
people hypothesize about them and show results upfront.
89+
90+
A SIP is submitted as a pull request against [the official Scala website
91+
repo](https://github.com/scala/scala.github.com). Within a week of receiving the
92+
pull request, the Process Lead will acknowledge your submission, validate it and
93+
engage into some discussions with the author to improve the overall quality of
94+
the document (if necessary).
95+
96+
When you and the Process Lead agree on the final document, it is formally
97+
accepted for review: assigned a reviewer and scheduled for formal presentation.
98+
99+
### Formal presentation (up to 1 month)
100+
101+
During the next available SIP Committee meeting, the appointed reviewer presents
102+
the SIP to the committee and kick starts the initial discussion.
103+
104+
If the Committee agrees that following through the SIP is a good idea, then the
105+
following happens:
106+
107+
1. The SIP is assigned a number.
108+
2. The SIP pull request is merged into the official Scala website repo, and the
109+
merged document becomes the official webpage of the proposal.
110+
3. An issue to discuss the SIP is opened at the official Scala website repo. Then,
111+
the reviewer submits the initial feedback from the committee.
112+
4. An implementation is requested (if not already present).
113+
114+
Otherwise, the SIP is rejected. The reviewer submits the collected feedback as a
115+
comment to the pull request, and the pull request is closed.
116+
117+
### Formal evaluation (up to 6 iterations)
118+
119+
Evaluation of a SIP is done in iterations. The maximum number of iterations is
120+
six. These iterations take place in the SIP meetings and are usually monthly.
121+
However, they can last longer, in which case the author has more time to
122+
implement all the required changes.
22123

23-
## What will happen next ##
124+
The committee decides the duration of the next iteration depending upon the
125+
feedback and complexity of the SIP. Consequently, authors have more time to
126+
prepare all the changes. If they finish their revision before the scheduled
127+
iteration, the Process Lead will reschedule it for the next available meeting.
24128

25-
The SIP committee will have a look at your proposal. If it is looks promising, it will be made into a SIP. At that point, you'll have to sign a CLA (contributor license agreement) which says that you are OK with the text of the proposal and the implementation being used in the Scala project.
129+
During every iteration, the appointed reviewer presents the changes (updated
130+
design document, progress with the implementation, etc) to the SIP Committee.
131+
Based on the feedback, the SIP is either:
26132

27-
## What will happen afterwards ##
133+
1. Accepted, in which case the committee will propose a release date to the
134+
compiler maintainers, where the role of the committee ends.
135+
2. Rejected, in which case the SIP is closed and no longer evaluated in the future.
136+
3. Postponed, in which case the reviewer responds to the committee’s feedback in
137+
the SIP issue tracker, and the SIP is scheduled for a follow-up discussion
138+
during the next SIP meeting.
28139

29-
The SIP will get a unique number. It should be discussed on the [scala-sips mailing list](https://groups.google.com/forum/#!forum/scala-sips).
30-
In these mails, every mail that is specific to a SIP ### should be prefixed with \[SIP-###\].
31-
Typically, a SIP under discussion will have a member of the committee as shepherd, to help move it forward.
140+
If no changes have been made to a SIP in two iterations, it’s marked as dormant
141+
and both the PR and issue are closed. Dormant SIPs can be reopened by any
142+
person, be it the same or different authors, at which point it will start from
143+
the formal evaluation phase.
32144

33-
Before a SIP can be accepted, it also needs a full implementation that can be evaluated in practice.
34-
That implementation can be done before the SIP is submitted, or else concurrently with the discussion period.
145+
### Merging the proposal
35146

36-
## What is the provisional voting status? ##
147+
If the SIP is accepted, the committee will propose a release date to the
148+
compiler maintainers, where the role of the committee ends. Accepted SIPs will
149+
then be merged under a flag. When SIPs introduce intricate changes and they
150+
cannot be merged under a flag, the compiler maintainers will merge it directly.
37151

38-
When a release is drawing near, the SIP committee will hold on provisional vote on pending SIPs. This vote places sips in one of the current status:
152+
## Structure of the process
39153

40-
* `Accepted` - The SIP will be included in the next release, pending an acceptable implementation.
41-
* `Deferred - Next Meeting` - The committee has concerned that need to be addressed in the SIP before inclusion in the Release. If the concerns are handled before the next release, the SIP will be re-evaluated.
42-
* `Delay - Next Release` - The SIP committee has larger concerns with the state of the SIP and would prefer to wait until the next Scala release to consider inclusion.
43-
* `Not Accepted` - The SIP committee feels the SIP is not needed for the Scala language and turns down the proposal, with an explanation of why.
154+
The SIP process involves the following parties:
44155

45-
## What happens for a Scala major release? ##
156+
1. The SIP Authors
157+
2. The Process lead
158+
3. The SIP Committee
46159

47-
Before a Scala release, the committee will make a final decision for each SIP whether it should be accepted, rejected, or delayed for the next release. Accepted SIPs will be rolled into an upcoming Scala release and placed in the accepted folder. Rejected SIPs will be left in the SIP repository under the "rejected sips" section. Delayed SIPs will remain pending.
160+
### The SIP Authors
48161

162+
Authors are responsible for building consensus within the community and
163+
documenting dissenting opinions before the SIP is officially discussed by the
164+
SIP committee. Their goal is to convince the committee that their proposal is
165+
useful and addresses pertinent problems in the language as well as interactions
166+
with already existing features. Authors can change over the lifecycle of the
167+
SIP.
49168

50-
## Who is on the SIP committee ##
169+
### The Process lead
51170

52-
Right Now:
171+
The Process lead is the responsible of the smooth running of SIPs and SLIPs. He
172+
or she appoints the committee members, calls the meetings monthly, assigns new
173+
proposals to the members, and ensures that all of them are discussed within a
174+
short period of time.
53175

54-
* Martin Odersky
55-
* Josh Suereth
56-
* Adriaan Moors
57-
* Seth Tisue
58-
* Dick Wall
59-
* Heather Miller
176+
### The SIP Committee
177+
178+
The SIP Committee is an experienced group of people with knowledge of the
179+
compiler internals, responsible for the strategic direction of Scala. Members
180+
are tasked with (a) communicating with the community, (b) weighing in pros and
181+
cons of every proposal, and (c) accepting, postponing or rejecting the proposal.
182+
183+
Committee members should be either individuals responsible for a specific part
184+
of the Scala codebase, committers or contributors of the Scala compiler.
185+
Exceptionally, members may also be important representatives of the community
186+
with a high technical knowledge to understand the implications of every proposal
187+
and participate into the discussions. The members are elected by the Process
188+
Lead based on their expertise and implication in the community.
189+
190+
The current committee members are:
191+
192+
- Martin Odersky (EPFL)
193+
- Adriaan Moors (Lightbend)
194+
- Erik Osheim (independent)
195+
- Heather Miller (Scala Center)
196+
- Seth Tisue (Lightbend)
197+
- Sebastien Doeraene (EPFL)
198+
- Eugene Burmako (EPFL)
199+
- Andrew Marki (independent)
200+
- Josh Suereth (Google)
201+
202+
### Reviewers
203+
204+
The Process Lead assigns every proposal to a member of the committee, which
205+
becomes the reviewer. The main tasks of the reviewer are the following:
206+
207+
1. Discuss unclear points with the authors,
208+
2. Help them address their issues and questions,
209+
3. Provide them feedback from the discussions in the meetings, and
210+
4. Explain the latest progress in every meeting.
211+
212+
### Voting
213+
214+
For a SIP to be accepted, it must fulfill two requirements:
215+
216+
- 70% of the committee votes in favor of it.
217+
- Martin Odersky does not veto it.
218+
219+
### Responsibilities of the members
220+
221+
- Review the proposals they are assigned to. The process lead will always notify
222+
them two weeks in advance, at minimum.
223+
- Play a role in the discussions, learn in advance about the topic if needed, and
224+
make up their mind in the voting process.
225+
- Decide which utilities should be inside the core module and are required by the
226+
compiler. The goal is to shrink it over time, and, where possible, move modules
227+
to the platform, that will be managed by the SLIP process.
228+
229+
### Guests
230+
231+
Experts in some fields of the compiler may be invited to concrete meetings as
232+
guests when discussing related SIPs. Their input would be important to discuss
233+
the current state of the proposal, both its design and implementation.
234+
235+
## Proposal states
236+
237+
The state of a proposal changes over time depending on the phase of the process
238+
and the decisions taken by the Committee. A given proposal can be in one of
239+
several states:
240+
241+
1. **Validated:** The Process Lead has validated the proposal and checked that
242+
meets all the formal requirements.
243+
2. **Numbered:** The Committee agrees that the proposal is a valid document and
244+
it’s worth considering it. Then, the Process Lead gives it a number.
245+
3. **Awaiting review:** The proposal has been scheduled to be reviewed for a
246+
concrete date.
247+
4. **Under review:** Once the author has delivered a new version, the proposal will
248+
be under review until the next available SIP meeting takes place.
249+
5. **Under revision:** Authors are addressing the issues pinpointed by the
250+
committee or working on the implementation.
251+
6. **Dormant:** When a SIP has been under revision for more than two iterations (that
252+
is, no progress has been made since the last review), it’s considered dormant,
253+
in which case any related activity will be paralysed and the Process Lead will
254+
not allocate more resources to it.
255+
7. **Postponed:** The SIP has been postponed under some concrete conditions. When these
256+
are met, the SIP can be resubmitted.
257+
8. **Rejected:** The SIP has been rejected with a clear and full explanation.
258+
9. **Accepted:** The SIP has been accepted and it’s waiting for the merge into the
259+
Scala compiler.
260+
261+
## How do I submit? ##
262+
263+
The process to submit is simple:
264+
265+
* Fork the Scala documentation repository, [http://github.com/scala/scala.github.com](http://github.com/scala/scala.github.com).
266+
* Create a new SIP file in the `sips/pending/_posts/`.
267+
* Make sure the new file follows the format: `YYYY-MM-dd-{title}.md`. Use the proposal date for `YYYY-MM-dd`.
268+
* Use the [Markdown Syntax](http://daringfireball.net/projects/markdown/syntax) to write your SIP.
269+
* Follow the instructions in the [README](https://github.com/scala/scala.github.com/blob/gh-pages/README.md) to build your SIP locally so you can ensure that it looks correct on the website.
270+
* Create a link to your SIP in the "pending sips" section of `index.md`
271+
* Commit your changes to your forked repository
272+
* Create a new [pull request](https://github.com/scala/scala.github.com/pull/new/gh-pages). This will notify the Scala SIP team.
60273

61-
We will ask new members to join from time to time. The committee decides collectively, but Martin reserves the final say if there is a disagreement.

0 commit comments

Comments
 (0)