Join GitHub today
GitHub is home to over 28 million developers working together to host and review code, manage projects, and build software together.Sign up
Guidelines for Standard ML Basis Library proposals [ DRAFT ]
This page is a draft of guidelines for what is required when submitting a SML Basis Library proposal. Please use issue 11 to discuss these guidelines.
There are three kinds of proposals for changing the Standard ML Basis Library
proposals for new modules or for new components for existing modules.
proposals that amend an existing Basis Library specification to change the behavior of existing functions, or to clarify or correct a poorly worded specification.
proposals to remove deprecated features.
Anyone is free to submit a proposal for changing the Standard ML Basis Library, but a proposal must meet the following requirements to be considered as a draft.
The proposal should have a short, but descriptive name.
The proposal is a formatted as a github wiki file written using github Markdown or one of the other supported formats. The actual Wiki file will have the name YYYY-DDD-NAME.ZZZ, where YYYY is the year of submission, DDD is the proposal number for the year, NAME is the proposal name, where spaces have been replaced with dashes, and ZZZ is the file-type suffix (e.g.,
mdfor Markdown). Proposal names should avoid punctuation characters.
When appropriate, proposals must a sample implementation that is written in Standard ML using only approved Basis Library features. When proposals depend on special runtime-system support or foreign librarys, the reference implementation should be written as a
functorover the runtime-system operations. In that case, an additional working implementation for some specific platform should also be provided.
When appropriate, proposals must include test cases.
Proposed interfaces and sample implementations should follow the Basis Library coding conventions (see below).
Additional details about the format and content of proposals are given below.
Format of proposal description
Proposals should follow the style of the Basis Library Specification manual
pages, but with some additional
sections. An example proposal that provides a template for future proposals
can be found in the
Proposals that include multiple interfaces (as opposed to a single interfaces
with multiple implementations), should be split into multiple wiki pages (one
per interface) with a root page that summarized the proposal. The root page
should follow the naming convention described above (i.e., YYYY-DDD-NAME.ZZZ)
and the other pages should be named YYYY-DDDA-NAME.ZZZ, where A is
c, etc., and ZZZ is the name of the API described by the page.
Sample implementations will be uploaded to the Basis Library github repository with the path Code/YYYY/DDD where the proposal number is YYY-DDD.
A sample implementation should be structured as one file per module (signature,
structure, or functor) using the file-name suffix convention of
.sml for structures, and
.fun for functors. The sample
implementation should also include a CM build file named
an MLB build file named
In addition to a reference implementation, proposals should also include
test cases when appropriate. The directory
provides a testing infrastructure. Using this infrastructure, each
module in a proposal will have its own test suite (although the tests
themselves can be in a single testing module) and will produce its
own results file.
Proposals for new Basis Library modules should follow the coding conventions used in the published version of the original specification. These conventions are
- Alphanumeric value identifiers are in mixed-case, with a leading lowercase
- Type identifiers are all lowercase, with words separated by underscores;
- Signature identifiers are in all capitals, with words separated by underscores;
OS_PATH. We refer to this convention as the signature convention.
- Structure and functor identifiers are in mixed-case, with initial letters of words capitalized; e.g.,
WideChar. We refer to this convention as the structure convention.
- Alphanumeric datatype constructors follow the signature convention; e.g.,
FOLLOW_ALL. In certain cases, where external usage or aesthetics dictates otherwise, the structure convention can be used. Within the Basis library, the only use of the latter convention occurs with the months and weekdays in
Mon. The one exception to this rule are the traditional constructors
- Exception identifiers follow the structure convention; e.g.,
Licensing and copyright
The copyright of a proposal, its APIs, reference implementations, and test suites belongs to the author(s) of the proposal, but to promote easy adoption, proposals must be released under a liberal licensing scheme. Specifically, all proposals, including the APIs contained in the proposal, must be released under the Creative Commons license, and the supporting reference implementations and test suites must be released under the MIT open source license. Wiki pages automatically include a footer that links to the Creative Commons license. Source code should include a header comment that specifies that the code is covered by the MIT open source license.