Skip to content

Latest commit

 

History

History
45 lines (27 loc) · 1.68 KB

semantic.readme.md

File metadata and controls

45 lines (27 loc) · 1.68 KB

#Semantic README v1.0.0-alpha

Summary

A project contains a README.md file containing the following synopsis.

  • Name
  • Badges
  • Details
    • description
    • requirements
    • license
  • Changes
  • Protocols
  • Support Channels

See our example Example Readme.

##Introduction

A well formatted synopsis should be meaningful and decisive. It is the pitch deck of your project while serving as a primary support channel for your user base.

As part of my push for semantic projects inspired by Tom Preston-Werner and (SemVer), I propose this simple set of rules and requirements to structure how projects handle their README File.

##Semantic README Specification

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.

  1. A README MUST be located within the projects root folder and SHALL be formatted using markdown syntax.

  2. A README MUST contain sections in the following orders. Name, description, change log, protocols, Documentation, and support channels.

  3. A README MUST begin with a #[Project Name].

  4. The README MUST include a description and SHOULD NOT exceed 3 Paragraphs.

  5. Once a project version has been released, an entry MUST be added to the change log section. Indicated using the following format.

[Major, Minor, Patch] | vX.Y.Z | YYYY-MM-DD

  1. A README MUST contain a protocol section listing and linking to project protocols.

  2. A README MUST include a link to the projects documentation.

  3. A README MUST include all available support channels for the project.