114 lines
8.6 KiB
Markdown
114 lines
8.6 KiB
Markdown
# Instructions for creating a [README.md](http://README.md)
|
||
|
||
Write a comprehensive README.md for the project. First, review thse instrucitons. If unsure about anything in these instructions, ask, but try to use your judgment and inherent knowledge first. Then review the project in full, observing what is *actually present*.
|
||
|
||
---
|
||
|
||
# The Inviolable Rule:
|
||
|
||
In writing the README.md, do not make up information about the project.
|
||
|
||
Only write about code and other aspects of the project that are present and that could be objectively observed by a human examining the repository.
|
||
|
||
---
|
||
|
||
# Content - Above The Fold
|
||
|
||
|
||
|
||
### Do:
|
||
|
||
Always use hierarchical headers (e.g. #, ##, ##) that demarcate and group content by topic or logical relation.
|
||
|
||
This information 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 as the first line (e.g. make is a command line tool for running builds based on a rules-based Makefile).
|
||
|
||
Hyperlink the first word (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. This is 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 spits out fun emoji and 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 using 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 extensive 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, OSes, dependencies, file formats, standards documents, etc. If there isn’t an “official” site for the entity, link a Wikipedia article. Make it very easy for people to get additional context if they want it (or to ignore it if they do not).
|
||
|
||
links in markdown are 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 markdown) if applicable. Avoid graphical screenshots if it is just text.]
|
||
|
||
[This should also be provided, ask for this if it is not]: Include the reason the project came into existence You do not need a whole brand story (unless you want to), 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, if any. For example, if you are a functional programming library, show some common functional programming usage examples before and after your library so people can understand why you exist.
|
||
|
||
Do include a top level “Getting Started” section for first-time users. This should include a quickstart guide (possibly 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.
|
||
|
||
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.
|
||
|
||
Include an explanation of the contribution process, if provided, and 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 should be that they will be accepted for review, but project authors make no guarantee that they will be merged.
|
||
|
||
Include a complete list of any contribution hard requirements. 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.
|
||
|
||
### Ideology
|
||
|
||
State what sort of community participants can expect. If you have a Code of Conduct, link it and list it by name. If you do not have one, mention 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 the so-called “open core” offering of a startup.
|
||
|
||
Make it clear if the project is one free software component of a larger system that includes nonfree software, or vice versa.
|
||
|
||
Make it clear if the project/software exists to interface with a single centralized service, and link to that service and its EULA or TOS.
|
||
|
||
Make it clear if the software is going to transmit user activity data off of the device on which it is run. Link to the associated privacy policy, if so. Assume it will not do so, as surveillanceware is evil.
|
||
|
||
### DO NOT:
|
||
|
||
These "DO NOTS" apply to the entirety of the README.md (both above and below the fold).
|
||
|
||
Do not assume the "above the fold" README.md audience has ever 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 too lengthy, as long as you always:
|
||
|
||
1. Write in concise language.
|
||
2. Favor short, declarative sentences.
|
||
3. Eliminate, wherever 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.
|
||
|
||
(If sections get too long, they can be factored out later to sub-files in a documentation directory at path /docs/ – and replaced with a link to those files. It is acceptable for the README.md to contain all of the primary documentation for a small project.)
|
||
|
||
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 of any kind. |