README

Template:Short description Template:Otheruses Template:Use dmy dates Template:Use list-defined references

Screenshot of the README file of cURL

In software distribution and software development, a README file contains information about the other files in a directory or archive of computer software. A form of documentation, it is usually a simple plain text file called README, Read Me, READ.ME, README.txt,<ref name="ESR_1996_Dict"/> or README.md (to indicate the use of Markdown)

The file's name is generally written in uppercase. On Unix-like systems in particular, this causes it to stand outTemplate:Sndboth because lowercase filenames are more common, and because the ls command commonly sorts and displays files in ASCII-code order, in which uppercase filenames will appear first.<ref group="nb" name="NB1"/>

ContentsEdit

A README file typically encompasses:

Configuration instructions
Installation instructions
Operating instructions
A file manifest (a list of files in the directory or archive)
Copyright and licensing information
Contact information for the distributor or author
A list of known bugs<ref name="Manes_1996"/>
Troubleshooting instructions<ref name="Manes_1996"/>
Credits and acknowledgments
A changelog (usually aimed at fellow programmers)
A news section (usually aimed at end users)

HistoryEdit

The convention of including a README file began in the mid-1970s.<ref name="Decus_1974_readme"/><ref name="Decus_1975_readme"/><ref name="PWB_1977"/><ref name="UNIX7_1979"/><ref name="BSD_1980"/><ref name="Langemeier_2011"/><ref name="Abdelhafith_2015"/> Early Macintosh system software installed a Read Me on the Startup Disk, and README files commonly accompanied third-party software.

In particular, there is a long history of free software and open-source software including a README file; the GNU Coding Standards encourage including one to provide "a general overview of the package".<ref name="GNU_Standards" />

Since the advent of the web as a de facto standard platform for software distribution, many software packages have moved (or occasionally, copied) some of the above ancillary files and pieces of information to a website or wiki, sometimes including the README itself, or sometimes leaving behind only a brief README file without all of the information required by a new user of the software.

The popular source code hosting website GitHub strongly encourages the creation of a README fileTemplate:Spaced ndashif one exists in the main (top-level) directory of a repository, it is automatically presented on the repository's front page.<ref>{{#invoke:citation/CS1|citation |CitationClass=web }}</ref> In addition to plain text, various other formats and file extensions are also supported,<ref name="Github_2014_Markup"/> and HTML conversion takes extensions into accountTemplate:Spaced ndashin particular a README.md is treated as GitHub Flavored Markdown.

As a generic termEdit

The expression "readme file" is also sometimes used generically, for other files with a similar purpose.Template:Citation needed For example, the source-code distributions of many free software packages (especially those following the Gnits Standards or those produced with GNU Autotools) include a standard set of readme files:

`README`	General information
`AUTHORS`	Credits
`THANKS`	Acknowledgments
`CHANGELOG`	A detailed changelog, intended for programmers
`NEWS`	A basic changelog, intended for users
`INSTALL`	Installation instructions
`COPYING` / `LICENSE`	Copyright and licensing information
`BUGS`	Known bugs and instructions on reporting new ones
`CONTRIBUTING` / `HACKING`	Guide for prospective contributors to the project

Also commonly distributed with software packages are an FAQ file and a TODO file, which lists planned improvements.

NotesEdit

Template:Reflist

ReferencesEdit