Common special files found in the root directory of a repository
Description for and list of popular special files like README/CHANGELOG/LICENSE and others.
README-like
README.md
README
ReadMe The ReadMe is usually the first document people will see of your project. Depending on your project it should give a short introduction and usage/build examples. It should only contain the information you expect users to read. It is usually possible to link to other documentation files using the markdown syntax which gets rendered as html by popular repository hosting platforms.
awesome-readme: List of good/awesome Readmes and links to How to write a good ReadMe.
CHANGELOG.md
CHANGELOG
(CHANGES
/HISTORY
/NEWS
/RELEASES
)
Change Log The change log lists all important changes between different, even unreleased, versions of your project. It should not contain every commit message, as that information may be too detailed and can be fetched from the version control system too.
- keepachangelog.com: How to keep a changelog
CONTRIBUTING.md
CONTRIBUTING
Contribution Guidelines In the open source world many people can easily contribute to your project. If you want to set certain guidelines that the contributors should respect they usually are found in this file.
On GitHub this file will be linked on the New Issue and New Pull Request pages, to increase contributor awareness for the guidelines.
SUPPORT.md
SUPPORT
Support resources This file is intended to let people know about ways to get help with your project.
On Github this file will be linked on the New Issue issue page (but, unlike the Contribution Guidelines, not on the New Pull Request page).
LICENSE.md
LICENSE
(COPYING
)
License It is important to explicitly state the license (or licenses) under which you publish your project. If you don't the default copyright laws apply.
If you have no experience in choosing a license you should consider contacting a lawyer, especially if your project contains other (licensed) work, (future) legal trademarks and other intellectual property that needs careful protection. There is also an online service that helps you choose a license: choosealicense.com
It is common that the name of the license is also mentioned in the ReadMe and links to the full text which is found in this LICENSE
file.
CONTRIBUTORS.md
CONTRIBUTORS
(see AUTHORS
)
List of Contributors Special list of people and/or organizations that have contributed to your project. Depending on your project and your contribution guidelines,
- contributors may decide themselves if they should appear in that list,
- they have to appear (by adding their name themselve) in that list or
- that only substantial contributions will be mentioned in that file by a responsible person of your project management team or you (see
AUTHORS
for this purpose)
AUTHORS.md
AUTHORS
(see CONTRIBUTORS
)
List of copyright holders/authors Legally relevant contributors/authors of the project should be listed in this file.
According to the GNU "Only the contributions that are legally significant for copyright purposes (see Legally Significant) need to be listed. Small contributions, bug reports, ideas, etc., can be omitted."
ACKNOWLEDGMENTS.md
ACKNOWLEDGMENTS
Acknowledgments Mentioning other work, their copyright notice and used license can be done in ACKNOWLEDGMENTS.md
.
If your project builds upon other software, parts of software (libraries) or simply work owned by someone else, it depends on their license how you have to acknowledge its usage in your project. Usually you have to state their copyright notice and license used somewhere in your project.
Other
CODE_OF_CONDUCT.md
Code of Conduct A more general and broad form of rules (than the ones in CONTRIBUTING
) that people interacting with your project have to obey.
See contributor-covenant.org for an example.
Platform-dependent features/templates
ISSUE_TEMPLATE
New Issue
PULL_REQUEST_TEMPLATE
New Pull Request
CODEOWNERS
Code Owners A CODEOWNERS file defines users who are resposible for code.
On GitHub, these users are automatically requested to review pull requests that modify code that they own.
Frequently Asked Questions
When should I name the file ending in .md?
In general only files that end in .md
will be rendered using markdown. So whenever you want to use markdown features that should be rendered visually (like headings/sections/lists/clickable links/bold/italic/...) you should use .md
.