Guidelines

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.

Overview

There are three kinds of proposals for changing the Standard ML Basis Library

1. proposals for new modules or for new components for existing modules.

2. proposals that amend an existing Basis Library specification to change the behavior of existing functions, or to clarify or correct a poorly worded specification.

3. 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.

1. The proposal should have a short, but descriptive name.

2. 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., md for Markdown). Proposal names should avoid punctuation characters.

3. 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 functor over the runtime-system operations. In that case, an additional working implementation for some specific platform should also be provided.

4. When appropriate, proposals must include test cases.

5. 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 Code/example directory.

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 a, b, c, etc., and ZZZ is the name of the API described by the page.

Sample implementations

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 .sig for signatures, .sml for structures, and .fun for functors. The sample implementation should also include a CM build file named sources.cm and an MLB build file named sources.mlb.

Test cases

In addition to a reference implementation, proposals should also include test cases when appropriate. The directory Code/testing 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.

Coding conventions

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 letter; e.g., map and openIn.
• Type identifiers are all lowercase, with words separated by underscores; e.g., word and file_desc.
• Signature identifiers are in all capitals, with words separated by underscores; e.g., PACK_WORD and 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., General and WideChar. We refer to this convention as the structure convention.
• Alphanumeric datatype constructors follow the signature convention; e.g., SOME, A_READ, and 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 Date, e.g., Jan and Mon. The one exception to this rule are the traditional constructors nil, true, and false.
• Exception identifiers follow the structure convention; e.g., Domain and SysErr.

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.

---