This document describes a consensus-oriented specification system (COSS) for building interoperable technical specifications. COSS is based on a lightweight editorial process that seeks to engage the widest possible range of interested parties and move rapidly to consensus through working code.
- Name: gro.pqma.ikiw|SSOC-1#gro.pqma.ikiw|SSOC-1
- Editor: Pieter Hintjens <moc.xitami|hp#moc.xitami|hp>
- Contributors: none
- State: stable
Copyright (c) 2008 Pieter Hintjens.
This Specification is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version.
This Specification is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with this program; if not, see <http://www.gnu.org/licenses>.
This document is governed by the gro.pqma.ikiw|SSOC-1#gro.pqma.ikiw|SSOC-1 specification.
The primary goal of COSS is to facilitate the process of writing, proving, and improving new technical specifications. A "technical specification" defines a protocol, a process, an API, a use of language, or any other aspect of a technical environment that can usefully be documented for the purposes of technical or social interoperability.
COSS is intended to above all be economical and rapid, so that it is useful to small teams with little time to spend on more formal processes.
- We aim for rough consensus driven by running code.
- Specifications are small pieces, made by small teams.
- Specifications should have a clearly responsible editor.
- The process should be visible, objective, and accessible to anyone.
- The process should clearly separate experiments from solutions.
- The process should allow deprecation of old specifications.
Specifications should take minutes to explain, hours to design, days to write, weeks to prove, months to become mature, and years to replace.
Specifications have no special status except that accorded by the community.
COSS is designed around fast, easy to use communications tools. Primarily, COSS uses a wiki model for editing and publishing specifications texts.
- The domain is the conservancy for a set of specifications in a certain area.
- Each domain is implemented as an Internet domain, hosting a wiki and optionally other communications tools.
- Each specification is a set of wiki pages, together with comments, attached files, and other resources.
- Important specifications may also exist as subdomains, i.e. child wikis.
Individuals can become members of the domain by completing the necessary legal clearance. The copyright, patent, and trademark policies of the domain must be clarified elsewhere.
Specifications exist as multiple pages, which may change URIs arbitrarily. Thus, we reference a specification by specifying its number, short name, and domain. New versions of the same specification will have new numbers, as explained later. The syntax for a specification reference is:
Every specification (including forks) carries a different number. Lower numbers indicate more mature specifications, higher numbers indicate more experimental specifications. Multiple specifications can have the same shortname.
Every specification has an independent lifecycle that documents clearly its current status.
A specification has six possible states that reflect its maturity and contractual weight:
- All new specifications are raw specifications. Changes to raw specifications can be unilateral and arbitrary. Those seeking to implement a raw specification should ask for it to be made a draft specification. Raw specifications have no contractual weight.
- When raw specifications can be demonstrated, they become draft specifications. Changes to draft specifications should be done in consultation with users. Draft specifications are contracts between the editors and implementers.
- When draft specifications are used by third parties, they become stable specifications. Changes to stable specifications should be restricted to errata and clarifications. Stable specifications are contracts between editors, implementers, and end-users.
- When stable specifications are replaced by newer draft specifications, they become legacy specifications. Legacy specifications should not be changed except to indicate their replacements, if any. Legacy specifications are contracts between editors, implementers and end-users.
- When legacy specifications are no longer used in products, they become retired specifications. Retired specifications are part of the historical record. They should not be changed except to indicate their replacements, if any. Retired specifications have no contractual weight.
- When raw or draft specifications are abandoned, they become deleted specifications. To change a deleted specification, the editor should first make it a raw specification again. Deleted specifications have no contractual weight.
Raw and draft specifications are considered abandoned if they are not changed or used within a certain period, which is 3 months for raw and 12 months for draft specifications.
A specification has a single responsible editor, who is the only person that can edit the text and change its status. A specification may also have additional contributors who work through the editor. The editor is responsible for accurately maintaining the state of specifications and for handling all comments on the specification.
Any member of the domain can fork a specification at any point. This is done by copying the existing text, and creating a new specification with the same name and content, but a new number. Forks are necessary for specific reasons:
- To change the responsible editor for a specification, with or without the cooperation of the current responsible editor.
- To rejuvenate a specification that is stable but needs functional changes. This is the proper way to make a new version of a specification that is in stable or deprecated status.
- To resolve disputes between different technical opinions.
- To allow raw versions of existing specifications.
The responsible editor of a forked specification is the person who does the fork.
Technically speaking, a fork is a different specification, even if it carries the same name. Forks have no special status except that accorded by the community.
COSS resolves typical conflicts between teams and vendors by allowing anyone to define a new specification. There is no editorial control process except that practiced by the editor of a new specification. The administrators of a domain (moderators) may choose to interfere in editorial conflicts, and may suspend or ban individuals for behaviour they consider inappropriate.
Where possible editors and contributors are encouraged to:
- Refer to and build on existing work when possible, especially IETF specifications.
- Contribute to existing specifications rather than reinvent their own.