saturneric/standard-readme
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Various wording/formatting adjustements

Browse Source 
This includes some additional guidelines, but is not intended to make any substantive changes.
This commit is contained in:
JesseWeinstein 2016-08-25 23:40:14 -07:00 committed by GitHub
parent a6c15b6b3e
commit 28c934ef62
1 changed files with 53 additions and 44 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

97
spec.md
View File

@ -1,55 +1,61 @@
## Specification # Specification
### Requirements A compliant README must satisfy all the requirements listed below.
A compliant README must: **Requirements:**
- Be called README.md (with capitalization). - Be called README.md (with capitalization).
- Be a valid Markdown file. - Be a valid Markdown file.
- Sections must appear in order delineated below. Optional sections may be omitted. - Sections must appear in order given below. Optional sections may be omitted.
- Sections must have the titles listed below, unless otherwise specified.
- Must be new lines between each section. - Must be new lines between each section.
**Suggestions:** **Suggestions:**
- A "Back to Top" link for longer sections can be useful, but is not required by any means. - A "Back to Top" link for longer sections can be useful, but is not required by any means.
### Sections ## Sections
#### Title ### Title
**Status:** Required. **Status:** Required.
**Requirements:** **Requirements:**
- Must match repository name. If it cannot, there must be a note in the long description about why. - Title must match repository and package manager names. If any of these don't match, there must be a note in the [Long Description](#long-description) explaining why.
- Must match package manager name. If it cannot, there must be a note in the long description about why.
**Suggestions:** **Suggestions:**
- Should be self-evident. - Should be self-evident.
#### Banner ### Banner
**Status:** Optional. **Status:** Optional.
**Requirements:** **Requirements:**
- Does not require its own title.
- Must link to local image in current repository. - Must link to local image in current repository.
- Must appear directly after the title. - Must appear directly after the title.
#### Badges ### Badges
**Status:** Optional. **Status:** Optional.
**Requirements:** **Requirements:**
- Does not require a title of its own.
- Must be newline delimited. - Must be newline delimited.
#### Short Description **Suggestions:**
**Status:** Required. - Use http://shields.io or a similar service to create and host the images.
### Short Description
**Status:** Required.
**Requirements:** **Requirements:**
- Does not require its own title.
- Must be less than 120 characters. - Must be less than 120 characters.
- Must start with `> ` - Must start with `> `
- Must be on it's own line. - Must be on it's own line.
- Must match the description in the packager manager's `description` field. - Must match the description in the packager manager's `description` field.
- Must match GitHub's description (if on GitHub). - Must match GitHub's description (if on GitHub).
**Suggestions:** **Suggestions:**
- Use [gh-description](https://github.com/RichardLitt/gh-description) to set and get GitHub description. - Use [gh-description](https://github.com/RichardLitt/gh-description) to set and get GitHub description.
- Use `npm show . description` to show the description from a local [npm](https://npmjs.com) package. - Use `npm show . description` to show the description from a local [npm](https://npmjs.com) package.
#### Long Description ### Long Description
**Status:** Optional. **Status:** Optional.
**Requirements:** **Requirements:**
- Must have no heading. - Does not require its own title.
**Suggestions:** **Suggestions:**
- If too long, consider moving to the [Background](#background) section. - If too long, consider moving to the [Background](#background) section.
@ -66,8 +72,7 @@ progressively greater amount of knowledge."
~ [Kirrily "Skud" Robert, perlmodstyle](http://perldoc.perl.org/perlmodstyle.html) ~ [Kirrily "Skud" Robert, perlmodstyle](http://perldoc.perl.org/perlmodstyle.html)
### Table of Contents
#### Table of Contents
**Status:** Required by default, optional for READMEs less than 100 lines. **Status:** Required by default, optional for READMEs less than 100 lines.
**Requirements:** **Requirements:**
- Must link to all Markdown sections in the file. - Must link to all Markdown sections in the file.
@ -77,55 +82,59 @@ progressively greater amount of knowledge."
**Suggestions:** **Suggestions:**
- May capture third and fourth depth headings. If it is a long ToC, these are optional. - May capture third and fourth depth headings. If it is a long ToC, these are optional.
#### Security ### Security
**Status**: Optional. **Status**: Optional.
**Requirements:** **Requirements:**
- May go here if visibility of security section is important. Otherwise, should be in [Extra Sections](#extra-sections). - May go here if it is important to highlight security concerns. Otherwise, it should be in [Extra Sections](#extra-sections).
#### Background ### Background
**Status:** Optional. **Status:** Optional.
**Requirements:** **Requirements:**
- Cover motivation. - Cover motivation.
- Cover abstract dependencies. - Cover abstract dependencies.
- Cover intellecutal provenance: A `See Also` section is also fitting. - Cover intellecutal provenance: A `See Also` section is also fitting.
#### Install ### Install
**Status:** Required by default, optional for doc modules. **Status:** Required by default, optional for doc modules.
**Requirements:** **Requirements:**
- Code block illustrating how to install. - Code block illustrating how to install.
Subsections: **Subsections:**
- `Dependencies`. Required if necessary. - `Dependencies`. Required if there are dependencies.
- `Updating`. Optional. - `Updating`. Optional.
**Suggestions:** **Suggestions:**
- Link to prerequisite sites for language: [npmjs](https://npmjs.com), [godocs](https://godoc.org), etc. - Link to prerequisite sites for programming language: [npmjs](https://npmjs.com), [godocs](https://godoc.org), etc.
- Include any system-specific information needed for Installation. - Include any system-specific information needed for installation.
- Subsection for dependencies needed for install to work.
- If there is no code in the module - for instance, a document-based module - this section is not required. - If there is no code in the module - for instance, a document-based module - this section is not required.
#### Usage ### Usage
**Status:** Required by default, optional for doc modules. **Status:** Required by default, optional for doc modules.
**Requirements:** **Requirements:**
- Code block illustrating common usage. - Code block illustrating common usage.
- If CLI compatible, code block indicating common usage. - If CLI compatible, code block indicating common usage.
- If importable, code block indicating both import functionality and usage. - If importable, code block indicating both import functionality and usage.
Subsections: **Subsections:**
- `CLI`. Required if CLI functionality exists. - `CLI`. Required if CLI functionality exists.
- If relevant, point to a runnable file for the usage code.
**Suggestions:** **Suggestions:**
- Cover basic choices that may affect usage: for instance, if JavaScript, cover promises/callbacks, ES6 here. - Cover basic choices that may affect usage: for instance, if JavaScript, cover promises/callbacks, ES6 here.
- If relevant, point to a runnable file for the usage code.
- If there is no code in the module - for instance, a document-based module - this section is not required. - If there is no code in the module - for instance, a document-based module - this section is not required.
#### Extra Sections ### Extra Sections
**Status**: Optional. **Status**: Optional.
**Requirements:** **Requirements:**
- None. - None.
#### API **Suggestions:**
**Status:** Optional. - Does not require its own title.
- Any other sections that are relevant should be added here, after [Usage](#usage) and before [API](#api).
- Specfically, the [Security](#security) section should be here if it wasn't important enough to be placed above.
### API
**Status:** Optional.
**Requirements:** **Requirements:**
- Describe exported functions and objects. - Describe exported functions and objects.
@ -135,8 +144,8 @@ Subsections:
- Describe caveats. - Describe caveats.
- If using an external API generator (like go-doc, js-doc, or so on), point to an external `API.md` file. This can be the only item in the section, if present. - If using an external API generator (like go-doc, js-doc, or so on), point to an external `API.md` file. This can be the only item in the section, if present.
#### Contribute ### Contribute
**Status**: Required. **Status**: Required.
**Requirements:** **Requirements:**
- State where users can ask questions. - State where users can ask questions.
- State whether PRs are accepted. - State whether PRs are accepted.
@ -148,8 +157,8 @@ Subsections:
- Link to the GitHub issues. - Link to the GitHub issues.
- Link to Code of Conduct. This is often in Contribute, or organization wide, so may not be necessary for each module. - Link to Code of Conduct. This is often in Contribute, or organization wide, so may not be necessary for each module.
#### License ### License
**Status:** Required. **Status:** Required.
**Requirements:** **Requirements:**
- State license initials or name. - State license initials or name.
- State license owner. - State license owner.