mirror of https://github.com/vacp2p/rfc.git
update(COSS): include RFC template (#518)
* update COSS (incl template); sembr * Update content/docs/rfcs/1/README.md Co-authored-by: Franck R. <franck@status.im> * Update content/docs/rfcs/1/README.md Co-authored-by: oskarth <ot@oskarthoren.com> * feedback: add myself as contributor Co-authored-by: ksr <kaiserd@users.noreply.github.com> Co-authored-by: Franck R. <franck@status.im> Co-authored-by: oskarth <ot@oskarthoren.com>
This commit is contained in:
Daniel Kaiser
GitHub
parent
f0efc9da7f
commit
26b3a33026
|
|
@ -3,6 +3,7 @@ slug: 1
|
||||||
title: 1/COSS
|
title: 1/COSS
|
||||||
name: Consensus-Oriented Specification System
|
name: Consensus-Oriented Specification System
|
||||||
status: draft
|
status: draft
|
||||||
|
category: Best Current Practice
|
||||||
editor: Oskar Thoren <oskar@status.im>
|
editor: Oskar Thoren <oskar@status.im>
|
||||||
contributors:
|
contributors:
|
||||||
- Pieter Hintjens <ph@imatix.com>
|
- Pieter Hintjens <ph@imatix.com>
|
||||||
|
|
@ -10,24 +11,37 @@ contributors:
|
||||||
- Alberto Barrionuevo <abarrio@opentia.es>
|
- Alberto Barrionuevo <abarrio@opentia.es>
|
||||||
- Chris Puttick <chris.puttick@thehumanjourney.net>
|
- Chris Puttick <chris.puttick@thehumanjourney.net>
|
||||||
- Yurii Rashkovskii <yrashk@gmail.com>
|
- Yurii Rashkovskii <yrashk@gmail.com>
|
||||||
|
- Daniel Kaiser <danielkaiser@status.im>
|
||||||
---
|
---
|
||||||
|
|
||||||
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.
|
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.
|
||||||
|
|
||||||
This specification is based on [Unprotocols 2/COSS](https://github.com/unprotocols/rfc/blob/master/2/README.md), used by the [ZeromMQ](https://rfc.zeromq.org/) project. It is equivalent except for a few areas:
|
This specification is based on [Unprotocols 2/COSS](https://github.com/unprotocols/rfc/blob/master/2/README.md), used by the [ZeromMQ](https://rfc.zeromq.org/) project.
|
||||||
|
It is equivalent except for some areas:
|
||||||
|
|
||||||
- Recommending the use of a permissive licenses, such as CC0 (with the exception of this document)
|
- recommending the use of a permissive licenses, such as CC0 (with the exception of this document);
|
||||||
- Misc metadata, editor, and format/link updates
|
- miscellaneous metadata, editor, and format/link updates;
|
||||||
|
- more inheritance from the [IETF Standards Process][https://www.rfc-editor.org/rfc/rfc2026.txt],
|
||||||
|
e.g. using RFC categories: Standards Track, Informational, and Best Common Practice;
|
||||||
|
- standards track specifications SHOULD follow a specific structure that both streamlines editing,
|
||||||
|
and helps implementers to quickly comprehend the specification
|
||||||
|
- specifications MUST feature a header providing specific meta information
|
||||||
|
|
||||||
## License
|
## License
|
||||||
|
|
||||||
Copyright (c) 2008-20 the Editor and Contributors.
|
Copyright (c) 2008-22 the Editor and Contributors.
|
||||||
|
|
||||||
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 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.
|
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.
|
You should have received a copy of the GNU General Public License along with this program;
|
||||||
|
if not, see http://www.gnu.org/licenses.
|
||||||
|
|
||||||
## Change Process
|
## Change Process
|
||||||
|
|
||||||
|
|
@ -35,17 +49,20 @@ This document is governed by the [1/COSS](spec/1) (COSS).
|
||||||
|
|
||||||
## Language
|
## Language
|
||||||
|
|
||||||
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC 2119](http://tools.ietf.org/html/rfc2119)
|
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in
|
||||||
|
[RFC 2119](http://tools.ietf.org/html/rfc2119).
|
||||||
|
|
||||||
## Goals
|
## Goals
|
||||||
|
|
||||||
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, a methodology, or any other aspect of a technical environment that can usefully be documented for the purposes of technical or social interoperability.
|
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, a methodology,
|
||||||
|
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.
|
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.
|
||||||
|
|
||||||
Principles:
|
Principles:
|
||||||
|
|
||||||
* We aim for rough consensus and running code.
|
* We aim for rough consensus and running code; [inspired by the IETF Tao](https://www.ietf.org/about/participate/tao/).
|
||||||
* Specifications are small pieces, made by small teams.
|
* Specifications are small pieces, made by small teams.
|
||||||
* Specifications should have a clearly responsible editor.
|
* Specifications should have a clearly responsible editor.
|
||||||
* The process should be visible, objective, and accessible to anyone.
|
* The process should be visible, objective, and accessible to anyone.
|
||||||
|
|
@ -58,22 +75,28 @@ Specifications have no special status except that accorded by the community.
|
||||||
|
|
||||||
## Architecture
|
## Architecture
|
||||||
|
|
||||||
COSS is designed around fast, easy to use communications tools. Primarily, COSS uses a wiki model for editing and publishing specifications texts.
|
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.
|
* 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 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.
|
* 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.
|
* 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 in an Intellectual Property policy that applies to the domain.
|
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 in an Intellectual Property policy that applies to the domain.
|
||||||
|
|
||||||
Specifications exist as multiple pages, one page per version of the specification (see "Branching and Merging", below), which may be assigned URIs that include an incremental number. Thus, we refer to a specification by specifying its domain, number, and short name. New versions of the same specification will have new numbers. The syntax for a specification reference is:
|
Specifications exist as multiple pages, one page per version of the specification (see "Branching and Merging", below), which may be assigned URIs that include an incremental number.
|
||||||
|
Thus, we refer to a specification by specifying its domain, number, and short name.
|
||||||
|
New versions of the same specification will have new numbers.
|
||||||
|
The syntax for a specification reference is:
|
||||||
|
|
||||||
<domain>/spec/<number>/<shortname>
|
<domain>/spec/<number>/<shortname>
|
||||||
|
|
||||||
For example, this specification is **rfc.vac.dev/spec/1/COSS**. The short form **1/COSS** may be used when referring to the specification from other specifications in the same domain.
|
For example, this specification is **rfc.vac.dev/spec/1/COSS**.
|
||||||
|
The short form **1/COSS** may be used when referring to the specification from other specifications in the same domain.
|
||||||
|
|
||||||
Every specification (including branches) carries a different number. Lower numbers indicate more mature specifications, higher numbers indicate more experimental specifications.
|
Every specification (including branches) carries a different number.
|
||||||
|
|
||||||
## COSS Lifecycle
|
## COSS Lifecycle
|
||||||
|
|
||||||
|
|
@ -84,56 +107,105 @@ A specification has six possible states that reflect its maturity and contractua
|
||||||
|
|
||||||
|
|
||||||
### Raw Specifications
|
### Raw Specifications
|
||||||
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.
|
|
||||||
|
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.
|
||||||
|
|
||||||
### Draft Specifications
|
### Draft Specifications
|
||||||
|
|
||||||
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 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.
|
||||||
|
|
||||||
### Stable Specifications
|
### Stable Specifications
|
||||||
When draft specifications are used by third parties, they become **stable** specifications. Changes to stable specifications should be restricted to cosmetic ones, errata and clarifications. Stable specifications are contracts between editors, implementers, and end-users.
|
|
||||||
|
When draft specifications are used by third parties, they become **stable** specifications.
|
||||||
|
Changes to stable specifications should be restricted to cosmetic ones, errata and clarifications.
|
||||||
|
Stable specifications are contracts between editors, implementers, and end-users.
|
||||||
|
|
||||||
### Deprecated Specifications
|
### Deprecated Specifications
|
||||||
|
|
||||||
When stable specifications are replaced by newer draft specifications, they become **deprecated** specifications. Deprecated specifications should not be changed except to indicate their replacements, if any. Deprecated specifications are contracts between editors, implementers and end-users.
|
When stable specifications are replaced by newer draft specifications, they become **deprecated** specifications.
|
||||||
|
Deprecated specifications should not be changed except to indicate their replacements, if any.
|
||||||
|
Deprecated specifications are contracts between editors, implementers and end-users.
|
||||||
|
|
||||||
### Retired Specifications
|
### Retired Specifications
|
||||||
|
|
||||||
When deprecated 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 deprecated 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.
|
||||||
|
|
||||||
### Deleted Specifications
|
### Deleted Specifications
|
||||||
|
|
||||||
Deleted specifications are those that have not reached maturity (stable) and were discarded. They should not be used and are only kept for their historical
|
Deleted specifications are those that have not reached maturity (stable) and were discarded.
|
||||||
value. Only Raw and Draft specifications can be deleted.
|
They should not be used and are only kept for their historical value.
|
||||||
|
Only Raw and Draft specifications can be deleted.
|
||||||
|
|
||||||
## Editorial control
|
## Editorial control
|
||||||
|
|
||||||
A specification MUST have a single responsible editor, the only person
|
A specification MUST have a single responsible editor,
|
||||||
who SHALL change the status of the specification through the lifecycle stages.
|
the only person who SHALL change the status of the specification through the lifecycle stages.
|
||||||
|
|
||||||
A specification MAY also have additional contributors who contribute changes to it. It is RECOMMENDED to use a process similar to [C4 process](https://github.com/unprotocols/rfc/blob/master/1/README.md) to maximize the scale and diversity of contributions.
|
A specification MAY also have additional contributors who contribute changes to it.
|
||||||
|
It is RECOMMENDED to use a process similar to [C4 process](https://github.com/unprotocols/rfc/blob/master/1/README.md)
|
||||||
|
to maximize the scale and diversity of contributions.
|
||||||
|
|
||||||
Unlike the original C4 process however, it is RECOMMENDED to use CC0 as a more permissive license alternative. We SHOULD NOT use GPL or GPL-like license. One exception is this specification, as this was the original license for this specification.
|
Unlike the original C4 process however, it is RECOMMENDED to use CC0 as a more permissive license alternative.
|
||||||
|
We SHOULD NOT use GPL or GPL-like license.
|
||||||
|
One exception is this specification, as this was the original license for this specification.
|
||||||
|
|
||||||
The editor is responsible for accurately maintaining the state of specifications and for handling all comments on the specification.
|
The editor is responsible for accurately maintaining the state of specifications and for handling all comments on the specification.
|
||||||
|
|
||||||
## Branching and Merging
|
## Branching and Merging
|
||||||
|
|
||||||
Any member of the domain MAY branch 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. The ability to branch a specification is necessary in these circumstances:
|
Any member of the domain MAY branch 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.
|
||||||
|
The ability to branch a specification is necessary in these circumstances:
|
||||||
|
|
||||||
* To change the responsible editor for a specification, with or without the cooperation of the current responsible editor.
|
* 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 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 resolve disputes between different technical opinions.
|
||||||
|
|
||||||
The responsible editor of a branched specification is the person who makes the branch.
|
The responsible editor of a branched specification is the person who makes the branch.
|
||||||
|
|
||||||
Branches, including added contributions, are derived works and thus licensed under the same terms as the original specification. This means that contributors are guaranteed the right to merge changes made in branches back into their original specifications.
|
Branches, including added contributions, are derived works and thus licensed under the same terms as the original specification.
|
||||||
|
This means that contributors are guaranteed the right to merge changes made in branches back into their original specifications.
|
||||||
|
|
||||||
Technically speaking, a branch is a *different* specification, even if it carries the same name. Branches have no special status except that accorded by the community.
|
Technically speaking, a branch is a *different* specification, even if it carries the same name.
|
||||||
|
Branches have no special status except that accorded by the community.
|
||||||
|
|
||||||
## Conflict resolution
|
## Conflict resolution
|
||||||
|
|
||||||
COSS resolves natural conflicts between teams and vendors by allowing anyone to define a new specification. There is no editorial control process except that practised 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.
|
COSS resolves natural conflicts between teams and vendors by allowing anyone to define a new specification.
|
||||||
|
There is no editorial control process except that practised 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.
|
||||||
|
|
||||||
|
## Specification Structure
|
||||||
|
|
||||||
|
### Meta Information
|
||||||
|
|
||||||
|
Specifications MUST contain the following metadata.
|
||||||
|
It is RECOMMENDED that specification metadata is specified as a YAML header (where possible).
|
||||||
|
This will enable programmatic access to specification metadata.
|
||||||
|
|
||||||
|
| Key | Value | Type | Example |
|
||||||
|
|------------------|----------------------|--------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|
||||||
|
| **shortname** | short name | string | 1/COSS |
|
||||||
|
| **title** | full name | string | Consensus-Oriented Specification System |
|
||||||
|
| **status** | status | string | draft |
|
||||||
|
| **category** | category | string | Best Current Practice |
|
||||||
|
| **tags** | 0 or several tags | list | waku-application, waku-core-protocol |
|
||||||
|
| **editor** | editor name/email | string | Oskar Thoren <oskar@status.im> |
|
||||||
|
| **contributors** | contributors | list | - Pieter Hintjens <ph@imatix.com><br> - André Rebentisch <andre@openstandards.de><br> - Alberto Barrionuevo <abarrio@opentia.es><br> - Chris Puttick <chris.puttick@thehumanjourney.net><br> - Yurii Rashkovskii <yrashk@gmail.com> |
|
||||||
|
|
||||||
|
### Specification Template
|
||||||
|
|
||||||
|
Standards Track specifications SHOULD be based on the [Vac RFC template](https://github.com/vacp2p/rfc/blob/master/content/docs/rfcs/template/README.md).
|
||||||
|
|
||||||
## Conventions
|
## Conventions
|
||||||
|
|
||||||
|
|
@ -155,17 +227,4 @@ It is RECOMMENDED to use color coding to indicate specification's status. Color
|
||||||
* 
|
* 
|
||||||
* 
|
* 
|
||||||
|
|
||||||
## Appendix B. Metainformation
|
|
||||||
|
|
||||||
It is RECOMMENDED that specification metadata is specified as a YAML header (where possible) or a separate YAML file. This will enable programmatic access
|
|
||||||
to specification metadata.
|
|
||||||
|
|
||||||
| Key | Value | Type | Example |
|
|
||||||
|------------------|----------------------|--------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|
|
||||||
| **domain** | specification domain | string | rfc.vac.dev |
|
|
||||||
| **shortname** | short name | string | 1/COSS |
|
|
||||||
| **name** | full name | string | Consensus-Oriented Specification System |
|
|
||||||
| **status** | status | string | draft |
|
|
||||||
| **tags** | 0 or several tags | list | waku-application, waku-core-protocol |
|
|
||||||
| **editor** | editor name/email | string | Oskar Thoren <oskar@status.im> |
|
|
||||||
| **contributors** | contributors | list | - Pieter Hintjens <ph@imatix.com><br> - André Rebentisch <andre@openstandards.de><br> - Alberto Barrionuevo <abarrio@opentia.es><br> - Chris Puttick <chris.puttick@thehumanjourney.net><br> - Yurii Rashkovskii <yrashk@gmail.com> |
|
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue