Skip to content

Guidelines

Jump to bottom Edit New page
John Reppy edited this page Aug 19, 2015 · 6 revisions

Guidelines for submitting a proposal [ DRAFT ]

This page is a draft of guidelines for what is required when submitting a SML Basis Library proposal

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.

TODO: provide a template file for proposals.

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 addtion to a reference implementation, proposals should also include test cases when appropriate.

TODO: develop a common testing infrastructure.

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

Creative Commons License
This document is licensed under a [Creative Commons Attribution 4.0 International License](http://creativecommons.org/licenses/by/4.0/).
Creative Commons License
This document is licensed under a [Creative Commons Attribution 4.0 International License](http://creativecommons.org/licenses/by/4.0/).
Add a custom sidebar
Clone this wiki locally