110 lines
8.0 KiB
Markdown
110 lines
8.0 KiB
Markdown
# Instructions for creating a [README.md](http://README.md)
|
||
|
||
Review these instructions. If unsure about anything in them, ask, but try to use your judgment and inherent knowledge first. Review the project in full, observing what is *actually present*. Write a comprehensive README.md for the project.
|
||
|
||
---
|
||
|
||
# The Inviolable Rule:
|
||
|
||
Do not make up information about the project. Only write about code and other aspects of the project that are present and that can be observed by a human examining the repository.
|
||
|
||
---
|
||
|
||
# Content - Above The Fold
|
||
|
||
### Do:
|
||
|
||
Use hierarchical headers (e.g. #, ##, ##) that demarcate and group content by topic or logical relation.
|
||
|
||
This should appear in the first ten to fifteen lines (as hard wrapped to no more than 80-100 cols) of the README.md.: A concise but complete description of the functionality and purpose of the software (e.g. make is a command line tool for running builds based on a rules-based Makefile).
|
||
|
||
Hyperlink the first word (which should be the name of the package) to the project's official website. If one is not provided, assume it is the same repo page on which the README.md appears, because people might be cloning the repo and viewing the README.md in other contexts, or offline ( e.g. [make](https://www.gnu.org/software/make/) ).
|
||
|
||
Include the primary programming language name in the first sentence description. Any tightly-coupled libraries (like React, for example) should also be mentioned. (e.g. written in C or written in [ES6](https://262.ecma-international.org/6.0/) and [JSX](https://facebook.github.io/jsx/) using [React](https://react.dev/) ).
|
||
|
||
Include the license name in the first sentence description, and link to the license’s info page. The default for all projects created pursuant to these instructions is the GNU General Public License: Released under the [GPL Version 3](https://opensource.org/license/gpl-3-0).
|
||
|
||
Include the approximate date of original release, as well as the current version and release date (check the current date from a verifiable outside source).
|
||
|
||
Make it clear who you envision the end user of the software to be: A command line helper app written by one person in a weekend that returns fun emoji versus a cloud-native API gateway proxy sidecar container that requires a working etcd cluster to start up are likely going to end up in daily use by very different types of users (or at least users in very different contexts).
|
||
|
||
e.g. for use by developers of large, complex, multi-language projects
|
||
e.g. for use by operators of large-scale Kubernetes clusters
|
||
e.g. for use by security administrators in regulated financial environments
|
||
|
||
Make liberal use of hyperlinks; err on the side of too many if you aren’t sure. Link everything that can be linked in the first section; company names, library names, programming language names, license types, distributions, OS, dependencies, file formats, standards documents, etc. If there isn’t an “official” site for an entity, link a Wikipedia article. Make it easy for people to get additional context.
|
||
|
||
Links in markdown are always in brackets with the URL in trailing parentheses: [Go](https://golang.org)
|
||
|
||
---
|
||
|
||
# Content - Below The Fold
|
||
|
||
Include the exact commands that one would need to copy and paste to build the project. Ideally this is only a few lines, as there should be build scripts or a Makefile or something of the like in the repo itself.
|
||
|
||
Include the exact commands that one would need to copy and paste to install the build prerequisites on the most common OS distributions. If the build system is anything other than make, that’s a dependency too and needs to be installed. Assume this is getting pasted into a completely fresh install VM. (e.g. apt-get install -y libfoo-dev libbar-dev libbaz3-dev cmake).
|
||
|
||
Mention whatever versioning scheme is used, whether SemVer or yyyymmdd.xx or yy.mm (like Ubuntu). If unsure, ask.
|
||
|
||
Include usage/invocation examples (with corresponding output) if the project is small or simple.
|
||
|
||
[The following should be provided and/or referenced by the human providing these instructions]: Include some text-based screenshots (or blocks or triple-backticks in markdow) if applicable. Avoid graphical screenshots if it is just text.
|
||
|
||
[This should also be provided, ask for it if it is not]: Include the reason the project came into existence You do not need a whole brand story, just a sentence or two is fine.
|
||
|
||
Include some information (with code examples) of any specialty programming language features or styles that the project focuses on.
|
||
|
||
Include a top level “Getting Started” section for first-time users. This should include a quickstart guide (inline in the README, or a link to the appropriate subsection of documentation, a link to the full documentation, and a link to the community participation section.)
|
||
|
||
### Participation
|
||
|
||
Include a top-level “Participation” section, with an explanation of the contribution process, if provided. It should:
|
||
|
||
State how bug reports will be accepted e.g. via email, or via Git issues (default, if not otherwise provided, should be Git issues).
|
||
|
||
Default statement on pull requests: they will be accepted for review, but project authors make no guarantee that they will be merged.
|
||
|
||
Include a list of contribution requirements, if any. Link to code style guidelines or linting configuration that must pass, if provided.
|
||
|
||
Be clear if a Contributor License Agreement (CLA) or other legal document is required to contribute. Default, if no further instruction is provided, is that a CLA is not required.
|
||
|
||
Include a top level “Authors” section that lists the names (or usernames) and email addresses of the maintainers or primary authors. Link to their personal pages/profiles if provided. Full names and websites are optional; email addresses are not. Try to make this reasonably complete, as it clarifies the size of the project management.
|
||
|
||
### Ideology
|
||
|
||
If the project has a Code of Conduct, link to it. If not, state that. Keep this transparent so people can make informed decisions about participation.
|
||
|
||
Make it clear if the project exists primarily as a tool for a for-profit company, such as a so-called “open core” offering of a startup.
|
||
|
||
State if the project is one free software component of a larger system that includes nonfree software, or vice versa.
|
||
|
||
State if the project/software exists to interface with a centralized service. Link to that service and its EULA or TOS.
|
||
|
||
Make it clear if the software will transmit activity data off the device where it runs. If it does, link to the privacy policy from the README.md.
|
||
|
||
### DO NOT:
|
||
|
||
These "DO NOTS" apply to the entirety of the README.md (above and below the fold).
|
||
|
||
Do not assume the README.md audience has heard of the authors or project.
|
||
|
||
Do not assume that the audience knows engineering/specialty jargon. Of course, technical language must be employed – this is a software project. But, the audience is the general web-using public. README.md language should endeavor to be accessible, not opaque.
|
||
|
||
Do not use acronyms, initials, or abbreviations without using the complete text for the first use, with the acronyms following thereafter.
|
||
|
||
e.g. Extract, Transform, Load (ETL)
|
||
e.g. Application Program Interface (API)
|
||
e.g. Software Development Kit (SDK)
|
||
|
||
Do not worry about the README.md being lengthy, as long as you:
|
||
|
||
1. Write in concise language.
|
||
2. Favor short, declarative sentences.
|
||
3. Eliminate, where possible, adverbs of "frequency or degree" (generally words ending in -ly, for example, "quickly," "completely," "easily").
|
||
4. Use logical section headings that demarcate content by subject.
|
||
|
||
(It is acceptable for the README.md to contain all of the primary documentation for a small/medium project. If sections get long, they can be refactored later to sub-files in a documentation directory at path /docs/ – and replaced here with a link to those files.)
|
||
|
||
Do not obfuscate email addresses; write them in full, make them links, clickable via mailto: URLs. Obfuscation is ineffective; spammers and web crawlers know how to use regex. The web is not the place to fight email spam. That is for email and network infrastructure.
|
||
|
||
DO NOT, ever, EVER use emojis. |