Well known files

Welcome to the Well-known files project. This repository contains all well-known files you could find in a GitHub repository.

Introduction

Besides code being tracked in a repository you typically find files which are for documentation purposes. They explain something such as how to get started , how to contribute or how to report security concerns.

These files usually are named in uppercase with and optional extension written in lowercase, e.g. README.md or LICENSE.

Table of contents

• Acknowledgements
• Authors
• Changelog
• Citation
• Cname
• Code of conduct
• Code owners
• Contributing
• Contributors
• Dependabot
• Funding
• Governance
• Issue templates
• License
• Pull request template
• Readme
• Security
• Support

Acknowledgements

This file explains relevant related work, such as other projects that are dependencies, or libraries, or modules, or have their own copyrights or licenses that you want to include in your project.

| | | |--------------------|-------------------------------------------------------------------| | File | ACKNOWLEDGEMENTS.md, ACKNOWLEDGMENTS.txt or ACKNOWLEDGMENTS | | Directories | ./, ./.github/ or ./docs/ | | Example | ./ACKNOWLEDGMENTS.md | | Additional reading | N/A |

Authors

This file lists people who are significant authors of the project, such as the people who are legally related to the work. Small contributions, bug reports, ideas, etc., can be omitted.

| | | |--------------------|------------------------------------------| | File | AUTHORS.md, AUTHORS.txt or AUTHORS | | Directories | ./, ./.github/ or ./docs/ | | Example | ./AUTHORS.md | | Additional reading | N/A |

Changelog

A CHANGELOG file describes the changes in the project, such as version changes, feature additions, and bug fixes.

| | | |--------------------|------------------------------------------------| | File | CHANGELOG.md, CHANGELOG.txt or CHANGELOG | | Directories | ./, ./.github/ or ./docs/ | | Example | ./CHANGELOG.md | | Additional reading | Keep a changelog |

Citation

This file explains how you would like people to cite your work. The citation file format is plain text with human-readable and machine-readable citation information. When you add this file to the default branch root directory of your repository, then GitHub automatically links to it from the repository landing page.

| | | |--------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------| | File | CITATION.cff | | Directories | ./ | | Example | ./CITATION.cff | | Additional reading | About CITATION files |

Cname

This file specifies the CNAMEs that should be directed to the generated site. It should be used in together with GitHub Pages when using a custom domain | | | |--------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------| | File | CNAME | | Directories | ./ | | Example | ./CNAME | | Additional reading | Managing a custom domain for your GitHub Pages site |

Code of conduct

This file explains how to engage in a community, and how to foster an inclusive environment that respects all people, and how to address any problems among members of your project's community.

| | | |--------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | File | CODE_OF_CONDUCT.md, CODE_OF_CONDUCT.txt or CODE_OF_CONDUCT | | Directories | ./, ./.github/ or ./docs/ | | Example | ./CODEOFCONDUCT.md | | Additional reading | Adding a code of conduct to your project |

Code owners

This file defines individuals or teams that are responsible for code in a repository.

Code owners are automatically requested for review when someone opens a pull request that modifies code that they own. When someone with admin or owner permissions has enabled required reviews, they also can optionally require approval from a code owner before the author can merge a pull request in the repository.

| | | |--------------------|-------------------------------------------------------------------------| | File | CODEOWNERS | | Directories | ./, ./.github/ or ./docs/ | | Example | ./CODEOWNERS | | Additional reading | About code owners |

Contributing

This file explains how people can contribute to the project. This file can help verify people are submitting well-formed pull requests and opening useful issues. GitHub links to this file, on the page "New Issue" and the page "New Pull Request".

| | | |--------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | File | CONTRIBUTING.md, CONTRIBUTING.txt or CONTRIBUTING | | Directories | ./, ./.github/ or ./docs/ | | Example | ./CONTRIBUTING.md | | Additional reading | Setting guidelines for repository contributors | | | Awesome-Contributing | | | CONTRIBUTING.md Generator |

Contributors

This file explains who has contributed to the project. When we use a CONTRIBUTORS file in our projects, we ask people how they want to be listed, such as by their name, handle, email address, website link, etc.

| | | |--------------------|---------------------------------------------------------| | File | CONTRIBUTORS.md, CONTRIBUTORS.txt or CONTRIBUTORS | | Directories | ./, ./.github/ or ./docs/ | | Example | ./CONTRIBUTORS.md | | Additional reading | N/A |

Dependabot

This file explains who has contributed to the project. When we use a CONTRIBUTORS file in our projects, we ask people how they want to be listed, such as by their name, handle, email address, website link, etc.

| | | |--------------------|----------------------------------------------------| | File | dependabot.yml | | Directories | ./.github/ | | Example | ./.github/dependabot.yml | | Additional reading | N/A |

Funding

You can configure your sponsor button by adding a file in your repository on the default branch. You can configure the button to include sponsored developers in GitHub Sponsors, external funding platforms, or a custom funding URL.

| | | |--------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | File | FUNDING.yml | | Directories | ./.github/ | | Example | ./.github/FUNDING.yml | | Additional reading | Displaying a sponsor button in your repository |

Governance

This file lets people know about how your project is governed. For example, it might discuss project roles and how decisions are made.

| | | |--------------------|---------------------------------------------------| | File | GOVERNANCE.md, GOVERNANCE.txt or GOVERNANCE | | Directories | ./, ./.github/ or ./docs/ | | Example | ./GOVERNANCE.md | | Additional reading | N/A |

Issue templates

When you add an issue template to your repository, project contributors will automatically see the template's contents in the issue body. Templates customize and standardize the information you'd like included when contributors open issues.

To add multiple issue templates to a repository create an ISSUETEMPLATE/ directory in your project root. Within that `ISSUETEMPLATE/directory you can create as many issue templates as you need, for exampleISSUE_TEMPLATE/bugs.md`.

| | | |--------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | File | ISSUE_TEMPLATE | | Directories | ./, ./.github/, ./docs/ or ./ISSUE_TEMPLATE/ | | Example | ./.github/ISSUE_TEMPLATE/bug.md | | Additional reading | About issue and pull request templates | | | Configuring the template chooser |

License

This file explains the repository's legal license, such as any legal rights, any copyright restrictions, etc. If you include a detectable license in your repository, people who visit your repository will see it at the top of the repository page.

| | | |--------------------|---------------------------------------------------------------------------------------------------------------------------------------------------| | File | LICENSE.md, LICENSE.txt or LICENSE | | Directories | ./, ./.github/ or ./docs/ | | Example | ./LICENSE.md | | Additional reading | GitHub documentation | | | Choose a license |

Pull request template

This file triggers project contributors to automatically see the template's contents in a new pull request body. The template can customize and standardize the information you'd like included when contributors create pull requests.

| | | |--------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | File | pull_request_template.md | | Directories | ./, ./.github/ or ./docs/ | | Example | ./.github/pullrequesttemplate.md | | Additional reading | Creating a pull request template for your repository | | | Using templates to encourage useful issues and pull requests |

Readme

This file is often the first item a visitor will see when visiting your repository, because GitHub automatically shows this file to repository visitors. README files in subdirectories will display when visitors view that subdirectory in the GitHub website.

| | | |--------------------|----------------------------------------------------------------------------------------------------------------------------------------------------| | File | README.md, README.txt or README | | Directories | ./ | | Example | ./README.md | | Additional reading | About READMEs | | | Awesome readme |

Security

This file explains the project's security policies, such as a list of versions that are currently being maintained with security updates. This file also provides instructions on how users can submit a report of a vulnerability.

GitHub links to this file, under the "Policy" link on the "Security" tab of your repository.

| | | |--------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | File | SECURITY.md, SECURITY.txt or SECURITY | | Directories | ./, ./.github/ or ./docs/ | | Example | ./SECURITY.md | | Additional reading | Adding a security policy to your repository | | | About repository security advisories |

Support

This file explains how a reader can get help with the repository and project. GitHub links this file on the page "New Issue". Unlike the "CONTRIBUTING" file, GitHub does not link this file on the page "New Pull Request".

| | | |--------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | File | SUPPORT.md, SUPPORT.txt or SUPPORT | | Directories | ./, ./.github/ or ./docs/ | | Example | ./SUPPORT.md | | Additional reading | Adding support resources to your project |