228 lines
8.3 KiB
Markdown
228 lines
8.3 KiB
Markdown
# Specification
|
|
|
|
A compliant README must satisfy all the requirements listed below.
|
|
|
|
**Requirements:**
|
|
- Be called README.md (with capitalization).
|
|
- If the project supports i18n, the file must be named accordingly: `README.de.md`, where `de` is the BCP 47 Language tag. For naming, prioritize non-regional subtags for languages.
|
|
- Be a valid Markdown file.
|
|
- Sections must appear in order given below. Optional sections may be omitted.
|
|
- Sections must have the titles listed below, unless otherwise specified.
|
|
- Must not contain broken links.
|
|
- If there are code examples, they should be linted in the same way as the code is linted in the rest of the project.
|
|
|
|
## Table of Contents
|
|
|
|
_Note: This is only a navigation guide for the specification, and does not define or mandate terms for any specification-compliant documents._
|
|
|
|
- [Sections](#sections)
|
|
- [Title](#title)
|
|
- [Banner](#banner)
|
|
- [Badges](#badges)
|
|
- [Short Description](#short-description)
|
|
- [Long Description](#long-description)
|
|
- [Table of Contents](#table-of-contents-1)
|
|
- [Security](#security)
|
|
- [Background](#background)
|
|
- [Install](#install)
|
|
- [Usage](#usage)
|
|
- [Extra Sections](#extra-sections)
|
|
- [API](#api)
|
|
- [Contribute](#contribute)
|
|
- [License](#license)
|
|
- [Definitions](#definitions)
|
|
|
|
## Sections
|
|
|
|
### Title
|
|
**Status:** Required.
|
|
|
|
**Requirements:**
|
|
- Title must match repository, folder and package manager names - or it may have another, relevant title with the repository, folder, and package manager title next to it in italics and in parentheses. For instance:
|
|
|
|
```markdown
|
|
# Standard Readme Style _(standard-readme)_
|
|
```
|
|
|
|
If any of the folder, repository, or package manager names do not match, there must be a note in the [Long Description](#long-description) explaining why.
|
|
|
|
**Suggestions:**
|
|
- Should be self-evident.
|
|
|
|
### Banner
|
|
**Status:** Optional.
|
|
|
|
**Requirements:**
|
|
- Must not have its own title.
|
|
- Must link to local image in current repository.
|
|
- Must appear directly after the title.
|
|
|
|
### Badges
|
|
**Status:** Optional.
|
|
|
|
**Requirements:**
|
|
- Must not have its own title.
|
|
- Must be newline delimited.
|
|
|
|
**Suggestions:**
|
|
- Use http://shields.io or a similar service to create and host the images.
|
|
|
|
### Short Description
|
|
**Status:** Required.
|
|
|
|
**Requirements:**
|
|
- Must not have its own title.
|
|
- Must be less than 120 characters.
|
|
- Must start with `> `
|
|
- Must be on its own line.
|
|
- Must match the description in the packager manager's `description` field.
|
|
- Must match GitHub's description (if on GitHub).
|
|
|
|
**Suggestions:**
|
|
- 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.
|
|
|
|
### Long Description
|
|
**Status:** Optional.
|
|
|
|
**Requirements:**
|
|
- Must not have its own title.
|
|
- If any of the folder, repository, or package manager names do not match, there must be a note here as to why. See [Title section](#title).
|
|
|
|
**Suggestions:**
|
|
- If too long, consider moving to the [Background](#background) section.
|
|
- Cover the main reasons for building the repository.
|
|
- "This should describe your module in broad terms,
|
|
generally in just a few paragraphs; more detail of the module's
|
|
routines or methods, lengthy code examples, or other in-depth
|
|
material should be given in subsequent sections.
|
|
|
|
Ideally, someone who's slightly familiar with your module should be
|
|
able to refresh their memory without hitting "page down". As your
|
|
reader continues through the document, they should receive a
|
|
progressively greater amount of knowledge."
|
|
|
|
~ [Kirrily "Skud" Robert, perlmodstyle](http://perldoc.perl.org/perlmodstyle.html)
|
|
|
|
### Table of Contents
|
|
**Status:** Required; optional for READMEs shorter than 100 lines.
|
|
|
|
**Requirements:**
|
|
- Must link to all Markdown sections in the file.
|
|
- Must start with the next section; do not include the title or Table of Contents headings.
|
|
- Must be at least one-depth: must capture all `##` headings.
|
|
|
|
**Suggestions:**
|
|
- May capture third and fourth depth headings. If it is a long ToC, these are optional.
|
|
|
|
### Security
|
|
**Status**: Optional.
|
|
|
|
**Requirements:**
|
|
- May go here if it is important to highlight security concerns. Otherwise, it should be in [Extra Sections](#extra-sections).
|
|
|
|
### Background
|
|
**Status:** Optional.
|
|
|
|
**Requirements:**
|
|
- Cover motivation.
|
|
- Cover abstract dependencies.
|
|
- Cover intellectual provenance: A `See Also` section is also fitting.
|
|
|
|
### Install
|
|
**Status:** Required by default, optional for [documentation repositories](#definitions).
|
|
|
|
**Requirements:**
|
|
- Code block illustrating how to install.
|
|
|
|
**Subsections:**
|
|
- `Dependencies`. Required if there are unusual dependencies or dependencies that must be manually installed.
|
|
|
|
**Suggestions:**
|
|
- Link to prerequisite sites for programming language: [npmjs](https://npmjs.com), [godocs](https://godoc.org), etc.
|
|
- Include any system-specific information needed for installation.
|
|
- If there is no code in the module - for instance, a document-based module - this section is not required.
|
|
- An `Updating` section would be useful for most packages, if there are multiple versions which the user may interface with.
|
|
|
|
### Usage
|
|
**Status:** Required by default, optional for [documentation repositories](#definitions).
|
|
|
|
**Requirements:**
|
|
- Code block illustrating common usage.
|
|
- If CLI compatible, code block indicating common usage.
|
|
- If importable, code block indicating both import functionality and usage.
|
|
|
|
**Subsections:**
|
|
- `CLI`. Required if CLI functionality exists.
|
|
|
|
**Suggestions:**
|
|
- 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.
|
|
|
|
### Extra Sections
|
|
**Status**: Optional.
|
|
|
|
**Requirements:**
|
|
- None.
|
|
|
|
**Suggestions:**
|
|
- Must not its own title. The sections included within it must have titles.
|
|
- This should contain any other sections that are relevant, placed after [Usage](#usage) and before [API](#api).
|
|
- Specifically, the [Security](#security) section should be here if it wasn't important enough to be placed above.
|
|
|
|
### API
|
|
**Status:** Optional.
|
|
|
|
**Requirements:**
|
|
- Describe exported functions and objects.
|
|
|
|
**Suggestions:**
|
|
- Describe signatures, return types, callbacks, and events.
|
|
- Cover types covered where not obvious.
|
|
- 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.
|
|
|
|
### Maintainer(s)
|
|
**Status**: Required.
|
|
|
|
**Requirements:**
|
|
- Must be called `Maintainer` or `Maintainers`.
|
|
- List maintainer(s) for a repository, along with one way of contacting them (e.g. GitHub link or email).
|
|
|
|
**Suggestions:**
|
|
- This should be a small list of people in charge of the repo. This should not be everyone with access rights, such as an entire organization, but the people who should be pinged and who are in charge of the direction and maintenance of the repository.
|
|
- Listing past maintainers is good for attribution, and kind.
|
|
|
|
### Contribute
|
|
**Status**: Required.
|
|
|
|
**Requirements:**
|
|
- State where users can ask questions.
|
|
- State whether PRs are accepted.
|
|
- List any requirements for contributing; for instance, having a sign-off on commits.
|
|
|
|
**Suggestions:**
|
|
- Link to a contributing or contribute file -- if there is one.
|
|
- Be as friendly as possible.
|
|
- 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.
|
|
- A subsection for listing contributors is also welcome here.
|
|
|
|
### License
|
|
**Status:** Required.
|
|
|
|
**Requirements:**
|
|
- State license full name or identifier, as listed on the [SPDX](https://spdx.org/licenses/) license list. For unlicensed repositories, add `UNLICENSED`. For more details, add `SEE LICENSE IN <filename>` and link to the license file. (These requirements were adapted from [npm](https://docs.npmjs.com/files/package.json#license)).
|
|
- State license owner.
|
|
- Must be last section.
|
|
|
|
**Suggestions:**
|
|
- Link to longer License file in local repository.
|
|
|
|
## Definitions
|
|
|
|
_These definitions are provided to clarify any terms used above._
|
|
|
|
- **Documentation repositories**: Repositories without any functional code. For instance, [RichardLitt/knowledge](https://github.com/RichardLitt/knowledge).
|