Skip to content

Latest commit

 

History

History
55 lines (41 loc) · 5.49 KB

SPECIFICATION-DOCUMENT-REQUIREMENTS.md

File metadata and controls

55 lines (41 loc) · 5.49 KB

Ethereum OASIS Open Project

Criteria for publishing specification documents

In addition to OASIS' basic criteria

Release

  • The document MUST clearly and accurately describe its current status, and the proposing group's expectations for its future (e.g. publishing schedule, final destiny, ...)
  • The document MUST conform to WCAG 2.1 level double-A
  • Links MUST NOT be broken on the date of publication
  • The document MUST use IETF's BCP14, i.e. RFC2119 and RFC8174 terminology for conformance
  • If replacing an existing version of a Project Specification, there MUST be a changes section with human-readable explanation of changes made

The following requirements are optional at this stage but become mandatory at later stages:

  • Each requirement in a spec SHOULD have a URL
  • Each requirement SHOULD be testable.
  • Specifications SHOULD describe security, privacy and internationalisation/localisation considerations. (For example, can human-readable text include language and direction information [see string-meta]? Is the protocol vulnerable to homoglyph attacks [see CVE-2021-42574]?)
  • Any requirement obsoleted since a previous version of the Project Specification SHOULD have a URL that resolves to somewhere explicitly stating the requirement is gone
  • Headings SHOULD have URLs that won't change, including fragment identifiers. (Including section numbers or similarly fragile details can make this more difficult.)
  • There SHOULD be an implementation experience document which contains a complete list of requirements, and an explanation of how at least two implementations (and preferably more) have implemented and determined that their implementations meet each requirement.

Project Specification Draft

  • The document MUST clearly and accurately describe its current status, and the proposing group's expectations for its future (e.g. publishing schedule, final destiny, ...)
  • The document MUST conform to WCAG 2.1 level double-A
  • Links MUST NOT be broken on the date of publication
  • The document MUST use IETF's BCP14, i.e. RFC2119 and RFC8174 terminology for conformance
  • If replacing an existing version of a Project Specification, there MUST be a changes section with human-readable explanation of changes made
  • Each requirement in a spec MUST have a URL
  • Each requirement MUST be testable.
  • Specifications MUST describe security, privacy and internationalisation/localisation considerations. (For example, can human-readable text include language and direction information [see string-meta]? Is the protocol vulnerable to homoglyph attacks [see CVE-2021-42574]?)
  • Any requirement obsoleted since a previous version of the Project Specification MUST have a URL that resolves to somewhere explicitly stating the requirement is gone

The following requirements are optional at this stage but become mandatory at later stages:

  • Headings SHOULD have URLs that won't change, including fragment identifiers. (Including section numbers or similarly fragile details can make this more difficult.)
  • There SHOULD be an implementation experience document which contains a complete list of requirements, and an explanation of how at least two implementations (and preferably more) have implemented and determined that their implementations meet each requirement.

Project Specification

  • The document MUST clearly and accurately describe its current status, and the proposing group's expectations for its future (e.g. publishing schedule, final destiny, ...)
  • The document MUST conform to WCAG 2.1 level double-A
  • Links MUST NOT be broken on the date of publication
  • The document MUST use IETF's BCP14, i.e. RFC2119 and RFC8174 terminology for conformance
  • If replacing an existing version of a Project Specification, there MUST be a changes section with human-readable explanation of changes made.
  • Each requirement in a spec MUST have a URL
  • Each requirement MUST be testable.
  • Specifications MUST describe security, privacy and internationalisation/localisation considerations. (For example, can human-readable text include language and direction information [see string-meta]? Is the protocol vulnerable to homoglyph attacks [see CVE-2021-42574]?)
  • Any requirement obsoleted since a previous version of the Project Specification MUST have a URL that resolves to somewhere explicitly stating the requirement is gone
  • Headings MUST have URLs that won't change, including fragment identifiers. (Including section numbers or similarly fragile details can make this more difficult.)
  • There MUST be an implementation experience document which contains a complete list of requirements, and an explanation of how at least two implementations (and preferably more) have implemented and determined that their implementations meet each requirement.