Readme-Guide.md

   1 # README guidelines
   2
   3 Every module in the expressjs, pillarjs, and jshttp organizations should have
   4 a README file named `README.md`. The purpose of the README is to:
   5
   6 - Explain the purpose of the module and how to use it.
   7 - Act as a landing page (both on GitHub and npmjs.com) for the module to help
   8   people find it via search. Middleware module READMEs are also incorporated
   9   into https://expressjs.com/en/resources/middleware.html.
  10 - Encourage community contributions and participation.
  11
  12 Use the [README template](https://github.com/expressjs/express/wiki/README-template)
  13 to quickly create a new README file.
  14
  15 ## Top-level items
  16
  17 **Badges** (optional): At the very top (with no subheading), include any
  18 applicable badges, such as npm version/downloads, build status, test coverage,
  19 and so on. Badges should resolve properly (not display a broken image).
  20
  21 Possible badges include:
  22 - npm version: `[![NPM Version][npm-image]][npm-url]`
  23 - npm downloads: `[![NPM Downloads][downloads-image]][downloads-url]`
  24 - Build status: `[![Build Status][travis-image]][travis-url]`
  25 - Test coverage: `[![Test Coverage][coveralls-image]][coveralls-url]`
  26 - Tips: `[![Gratipay][gratipay-image]][gratipay-url]`
  27
  28 **Summary**: Following badges, provide a one- or two-sentence description of
  29 what the module does. This should be the same as the npmjs.org blurb (which
  30 comes from the description property of `package.json`). Since npm doesn't
  31 handle markdown for the blurb, avoid using markdown in the summary sentence.
  32
  33 **TOC** (Optional): For longer READMEs, provide a table of contents that has
  34 a relative link to each section. A tool such as
  35 [doctoc](https://www.npmjs.com/package/doctoc) makes it very easy to generate
  36 a TOC.
  37
  38 ## Overview
  39
  40 Optionally, include a section of one or two paragraphs with more high-level
  41 information on what the module does, what problems it solves, why one would
  42 use it and how.  Don't just repeat what's in the summary.
  43
  44 ## Installation
  45
  46 Required. This section is typically just:
  47
  48 ```sh
  49 $ npm install module-name
  50 ```
  51
  52 But include any other steps or requirements.
  53
  54 NOTE: Use the `sh` code block to make the shell command display properly on
  55 the website.
  56
  57 ## Basic use
  58
  59 - Provide a general description of how to use the module with code sample.
  60   Include any important caveats or restrictions.
  61 - Explain the most common use cases.
  62 - Optional: a simple "hello world" type example (where applicable). This
  63   example is in addition to the more comprehensive [example section](#examples)
  64   later.
  65
  66 ## API
  67
  68 Provide complete API documentation.
  69
  70 Formatting conventions: Each function is listed in a 3rd-level heading (`###`),
  71 like this:
  72
  73 ```
  74 ### Function_name(arg, options [, optional_arg]  ... )
  75 ```
  76
  77 **Options objects**
  78
  79 For arguments that are objects (for example, options object), describe the
  80 properties in a table, as follows. This matches the formatting used in the
  81 [Express API docs](https://expressjs.com/en/4x/api.html).
  82
  83 |Property | Description | Type | Default|
  84 |----------|-----------|------------|-------------|
  85 |Name of the property in `monospace`. | Brief description | String, Number, Boolean, etc. | If applicable.|
  86
  87 If all the properties are required (i.e. there are no defaults), then you
  88 can omit the default column.
  89
  90 Instead of very lengthy descriptions, link out to subsequent paragraphs for
  91 more detailed explanation of specific cases (e.g. "When this property is set
  92 to 'foobar', xyz happens; see &lt;link to following section &gt;.)
  93
  94 If there are options properties that are themselves options, use additional
  95 tables. See [`trust proxy` and `etag` properties](https://expressjs.com/en/4x/api.html#app.settings.table).
  96
  97 ## Examples
  98
  99 Every README should have at least one example; ideally more.  For code samples,
 100 be sure to use the `js` code block, for proper display in the website, e.g.:
 101
 102 ```js
 103 var csurf = require('csurf')
 104 ...
 105 ```
 106
 107 ## Tests
 108
 109 What tests are included.
 110
 111 How to run them.
 112
 113 The convention for running tests is `npm test`. All our projects should follow
 114 this convention.
 115
 116 ## Contributors
 117
 118 Names of module "owners" (lead developers) and other developers who have
 119 contributed.
 120
 121 ## License
 122
 123 Link to the license, with a short description of what it is, e.g. "MIT" or
 124 whatever. Ideally, avoid putting the license text directly in the README; link
 125 to it instead.