Abstract

This document introduces the Scala Improvement Proposal (SIP) process. A SIP is a document that describes a proposed change to the Scala language, provides information to the Scala community, or describes a process related to the Scala language. A SIP should provide a concise summary of its contents and rationale.

We intend SIPs to be the primary mechanism for proposing and defining changes to the Scala language, collecting input from the Scala community, and documenting other decisions concerning the evolution of Scala. The SIP process has been greatly influenced by the Python Enhancement Proposal (PEP) process used by the Python community. We appreciate their efforts in this area.

SIP Types

A SIP may be one of three types:

1. A Standards SIP describes a change to the Scala language. Hypothetical SIPs of this type might include "Removing null values" or "Adding first class universal type quantification".
2. An Informational SIP describes a Scala design issue, or provides general guidelines or information to the Scala community, but does not propose a new feature. Informational SIPs do not necessarily represent a Scala community consensus or recommendation, so users and implementers are free to ignore Informational SIPs or follow their advice. Hypothetical SIPs of this type might be "Guidelines for formatting your Scala code" and "Why the use of the null value is a terrible idea".
3. A Process SIP describes a process surrounding Scala, or proposes a change to (or an event in) a process. Process SIPs are like Standards SIPs but apply to areas other than the Scala language itself. They often require community consensus; unlike Informational SIPs, they are more than recommendations, and users are typically not free to ignore them. An example of a SIP of this type is this document itself. Hypothetical SIPs of this type might be "Guidelines for making new releases" or "Reporting bugs in the Scala tool-chain". Any meta-SIP is also considered a Process SIP.

The SIP Life-cycle

During its SIP lifetime, a SIP will travel through some subset of the following states:

The SIP Workflow

Conception

The SIP process starts when someone has an idea for improving the Scala language, tools, or libraries, providing useful information to the community in a standardized format, or an idea for a new process that could be used as part of Scala development by the community.

As a rule of thumb, changes to the Scala tools, library, or documentation that can be expressed as a patch smaller than twenty-four lines (in unified diff format) should probably be submitted to the Scala bug tracking system, rather than as a SIP. However, if a change, no matter how small, has significant consequences, especially in terms of backwards compatibility, it would be best to incorporate it into a SIP.

At this stage, the SIP is not actually a SIP proper, but what we will call a pre-SIP. Pre-SIPs become SIPs proper once entering the draft stage.

Every pre-SIP, and consequently all SIPS, must have at least one owner. Ownership may be transferred. It is the responsibility of the owners to champion their pre-SIP or SIP and shepherd it through its life-cycle.

Once the owners of a pre-SIP feel that it is ready for review, the pre-SIP moves into the submission phase of its life-cycle. A pre-SIP is ready if it contains a clear, concise, and complete description of its purpose and scope, along with sufficient motivation for its existence.

Submission

After an initial version of a pre-SIP has been drafted in the format described by this document, its owners should submit it to the SIP Editorial Board at the e-mail address scala-sip@listes.epfl.ch.

The submission should take the form of a URI pointing to the pre-SIP. This URI will be treated as the official home of the SIP until it has entered accepted stage. Therefore, it should ideally be hosted at stable location. If circumstances should require that a SIP be moved, the owners should inform the SIP Editorial board.

Additionally, as part of the submission process the pre-SIP's owners must sign and submit copies of the Scala Software Grant and Individual Contributor License Agreement.

Once submitted, one or more members of the SIP Editorial Board will then begin reviewing the pre-SIP submission to decide whether it should be rejected or promoted to the draft stage.

After review by the editorial board, the pre-SIP can either be rejected or made into a SIP proper by moving it to the draft stage.

If the pre-SIP is rejected at this stage, the editorial board may indicate that resubmission is possible after the owners make revisions based upon their recommendations. Common reasons for rejecting a pre-SIP might be that the owners have not provided sufficient motivation, that the pre-SIP is technically unsound, the pre-SIP does not adequately address backwards compatibility issues, etc.

The review of a submitted pre-SIP should generally take no longer than a month.

All disagreements concerning the suitability of a pre-SIP will be arbitrated by the Benevolent Autarch for Life (BAFL), Martin Odersky. His decisions are final.

Draft

A pre-SIP that has entered this stage of its life-cycle will be assigned a unique SIP number by the SIP Editorial Board and the URI for the pre-SIP will added to the index of SIPs. At this point a pre-SIP is now a proper SIP.

A SIP remains in the draft stage until the owners feel it is sufficiently fleshed out to be ready for approval. Owners will generally gauge this state of readiness based upon the comments given in the SIP Editorial Board's review and feedback from the Scala community. A SIP that involves changes to the Scala language, tools, or library does not necessarily require a completed reference implementation to be approved. However, the SIP must specify the changes that will be made in sufficient detail that there can be no question that an implementation is possible and technically sound. It would be best if the SIP can be completed within six months of its approval.

Should the owners decide that a SIP is no longer sensible, the SIP is moved to the withdrawn state.

When ready, the owners will contact the SIP Editorial Board to initiate the approval process. Depending upon the SIP Editorial Board's decision, the SIP then moves into the accepted stage or the rejected state. It is also possible that the SIP Editorial Board will decide that the SIP is not yet ready, and that it will remain in the draft stage. Again, all disputes are arbitrated by the BAFL, with his decision being final.

Accepted

When is SIP approved by the SIP Editorial Board, the document is updated to indicate that it has entered the accepted stage, and the document and auxiliary files are checked into the central SIP Subversion repository. A SIP remains in this stage until the necessary implementation work, should it be a standards SIP, or all the steps necessary to put the process into place, should it be a process SIP, have been completed.

When all prerequisites and dependencies are in place, a SIP in this stage, can be moved into the active state if it is a process SIP or into the final state if it is a standards or informational SIP.

Active

A SIP that is in this state indicates that it is a process that is currently active. For example, this SIP itself is an active SIP.

If at some point an active SIP is obsoleted by a SIP that has become newly active, the original SIP is moved into the defunct state.

With approval from the SIP Editorial Board, minor changes and clarifications may be added to an active SIP, rather than requiring a completely new SIP be initiated. For example, were the space of possible SIP numbers be exhausted, this SIP will require a minor change to describe a new numbering scheme.

Final

A standards SIP in this state indicates it is now part of the Scala language, tool-chain, or libraries.

An informational SIP in this state is considered complete with respect to the time it was published. For example, an informational SIP describing code formatting guidelines would we considered complete with respect to the Scala language at the time it was originally published. If the language changes such that a new guide is necessary, either a completely new informational SIP should be submitted to replace the original, or a SIP specifying amendments to the original guidelines should be submitted.

If at some point a final SIP is obsoleted or replaced by a SIP that has become finalized, the original SIP is moved into the defunct state.

Rejected

If a pre-SIP enters this state, then nothing happens unless the owners decide that they can revise their pre-SIP and attempt to resubmit. If a proper SIP enters this state, the SIP document is updated to indicate that it has entered the rejected stage. Additionally, the document and auxiliary files are checked into the central SIP Subversion repository to maintain a record of it for the benefit of future discussions and posterity.

Withdrawn

If a SIP enters this state, the SIP document is updated to indicate that it has entered the withdrawn state. Additionally, the document and auxiliary files are checked into the central SIP Subversion repository to maintain a record of it for the benefit of future discussions and posterity.

Defunct

If a SIP enters this state, the SIP document is updated to indicate that it has become obsolete or replaced by one or more SIPs. However, the SIP remains in the repository to maintain a record of it for the benefit of future discussions and posterity.

Contents of a SIP

SIP document format

SIPs are UTF-8 encoded XHTML documents whose headers contain meta-data about the proposal. The file-name of a SIP document is sip-XXXXX.xhtml, where XXXXX denotes the SIP number. A typical SIP document has the following form (a template is available here):

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
  <title>[sip title]</title>
  <meta name="sip" content="XXXXX"       />
  <meta name="author" content="[list of authors]"       />
  <meta name="version" content="0"       />
  <meta name="type" content="[sip type]"       />
  <meta name="status" content="submission"       />
  <meta name="created" content="[yyyy-mm-dd]"       />
  <meta name="updated" content="[yyyy-mm-dd]"       />
  <!-- <meta name="scala-version" content="[scala version string]"       /> -->
  <!-- <meta name="owner-contact" content="[URI]"       /> -->
  <!-- <meta name="discussion" content="[URI]"       /> -->
  <!-- <link rel="auxiliary" href="[URI]" type="[mime type]"       /> -->
  <!-- <link rel="replaces" href="[URI]" type="application/xhtml+xml"       /> -->
  <!-- <link rel="depends-on" href="[URI]" type="application/xhtml+xml"       /> -->
  <!-- Stylesheet -->
  <link rel="stylesheet" href="http://lampsvn.epfl.ch/svn-repos/scala/sip/trunk/sip.css" type="text/css"       />
</head>
<body>
  <h1>[sip title]</h1>
  <p>Copyright &copy; [year], [authors]</p>
  <h2>Abstract</h2>

</body>
</html>

SIP headers

SIP documents must contain metadata in their headers, expressed with the XHTML tags <title>,<meta>, and <link>. The following list denotes the set of possible metadata of a SIP. Elements marked with a * may occur zero or more times, and elements marked with ? may occur zero or one times. All other elements are required.

<title>[sip title]</title>

The title of the SIP, whose length should not exceed 60 characters.

<meta name="sip" content="[sip number]" />

The SIP number. When filing a pre-SIP at the submission stage, this should be set to XXXXX. The SIP Editorial Board will then assign a new number to the proposal.

<meta name="author" content="[list of authors]" />

The author(s) of the SIP, a comma-separated list of (real) first- and last-names.

<meta name="version" content="[version number]" />

Version number of the SIP. A pre-SIP has a version number of 0. When a pre-SIP is promoted to the draft stage the version number becomes 1. Any subsequent revisions submitted to the SIP Editorial Board should have a revision number greater than the one presently in the Subversion repository.

<meta name="type" content="[sip type]" />

The type of the SIP, either standards, informational or process. The three SIP types are explained in section SIP types.

<meta name="status" content="[sip status]" />

Status of the SIP. When submitting a pre-SIP, the status should be set to submission. Possible values are: submission, draft, accepted, rejected, withdrawn, active, final, defunctand active. The status of a pre-SIP and proper SIP changes as described by the SIP life-cycle.

<meta name="created" content="[creation date]" />

Creation date of the pre-SIP, formatted as specified by ISO 8601, e.g. yyyy-mm-dd.

<meta name="updated" content="[update date]" />

Last update date of the SIP, also formatted as specified by by ISO 8601.

<meta name="scala-version" content="[scala version string]" />?

Scala versions to which this SIP applies. A single version may be specified (2.7.1.final), or a range (2.6.1.final-2.7.1.final). Ranges may also be open (-2.6.1.final or2.7.1.final-). This field is optional.

<meta name="owner-contact" content="[URI]" />*

This field may be used to provide a way to contact for the SIP's owners. This field will usually contain :mailto URI. To avoid issues of e-mail address harvesting, this field is optional.

<meta name="discussion" content="[URI]" />?

This field may be used to provide a pointer to a mailing list or web forum for the discussion of the SIP. This field is optional.

<link rel="auxiliary" href="[URI]" type="[mime type]" />*

These links provide references to auxiliary files supplied with the SIP. There should be as many instances of this field as there are auxiliary files for the SIP.

<link rel="replaces" href="[URI]" type="application/xhtml+xml" />*

These links provide references to SIPs that this SIP replaces. There may be zero or more occurrences of this field.

<link rel="replaced-by" href="[URI]" type="application/xhtml+xml" />*

These links provide references to SIPs that replace this SIP. There may be zero or more.

<link rel="obsoleted-by" href="[URI]" type="application/xhtml+xml" />*

These links provide references to SIPs that make this SIP obsolete. There may be zero or more occurrences of this field.

<link rel="depends-on" href="[URI]" type="application/xhtml+xml" />*

These links provide references to SIPs that this SIP depends upon. There may be zero or more occurrences of this field.

<link rel="stylesheet" href="http://lampsvn.epfl.ch/svn-repos/scala/sip/trunk/sip.css" type="text/css" />

The standard SIP stylesheet. Every SIP should exclusively reference this stylesheet.

XHTML guidelines

The title of the SIP is given using a <h1> heading and the sections of a SIP, such as Abstract, Motivation, Specification, etc., with <h2> headings. Depending on the needs, submitters are free to use <h3> and <h4> for finer granularity.

The body of a SIP is in general allowed to contain any XHTML data. However, everything related to formatting or layout should be omitted. This makes it easier to mechanically process SIPs. CSS should be avoided (except for the standard sip.css mentioned above). This makes it easier for a SIP to be formatted as needed. More specifically, the following tags are recommended:

<p>, <a>, <abbr>, <acronym>, <del>, <dfn>, <em>, <ins>, <samp>, <strong>, <sub>, <sup>

Paragraphs, hyperlinks and text decoration.

<ol>, <ul>, <dl>, <li>, <dt>, <dd>

Different sorts of lists (ordered, unordered, definition lists).

<table>, <thead>, <tbody>, <tfoot>, <t>, <td>

Tables

<code>

This tag should be used for in-line code fragments.

<pre>

Pre-formatted text, for instance to include multi-line source code samples or console output.

<img>, <object>

Read the section about Auxiliary Files to learn how to include image (and other) files in a SIP.

Feel free to add id attributes to any tags and hyperlink between different parts of a SIP.

Auxiliary Files

A SIP can have auxiliary files attached. The file-names of external files have the form sip-XXXXX-Y.ext, where XXXXX is the SIP number, Y is a number counting through the attached files, and ext is the file extension.

It is recommended that auxiliary files be provided in a format that is loss-less and easily edited with free and open tools. Recommended file types include PNG (.png), SVG (.svg), Scala / Java / C# source files (.scala / .java / .cs), patches (.patch), TeX (.tex), and plain text (.txt).