GitHub uses special files such as README
and LICENSE
, and special paths such as /.github
and /docs
, to improve repository managment and developer interactions. This page is a summary. We welcome pull requests.
- Introduction
- CODE_OF_CONDUCT
- CODEOWNERS
- CONTRIBUTING
- ISSUE_TEMPLATE
- Jekyll
- LICENSE
- PULL_REQUEST_TEMPLATE
- README
- SECURITY
GitHub special files can typically be written with a variety of formats and file name extensions:
-
Freeform text, such as
README
orREADME.txt
. -
Markup formats, such as
README.markdown
orREADME.asciidoc
- see markups -
Custom syntaxes, such as the file
CODEOWNERS
.
GitHub special files are typically located at the repository top level or in special paths:
-
/.github
is a hidden dot file directory. -
/docs
is a typical documentation directory. -
Custom paths, such as the directory
ISSUE_TEMPLATE
.
The special files and paths are sometimes also known as community health files, recommended repository files, well-known configurations, etc.
For a general overview see building a strong community and GitHub's Open Source Guides.
- Help: https://help.github.com/articles/adding-a-code-of-conduct-to-your-project/
- Awesome list: https://i-sight.com/resources/18-of-the-best-code-of-conduct-examples/
CODE_OF_CONDUCT
is a file that explains how to engage in a community, and how to inclusive environment that respects all people, and how to address any problems among members of your project's community.
https://help.github.com/articles/about-codeowners/
CODEOWNERS
is a file that 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.
- Help: https://help.github.com/articles/setting-guidelines-for-repository-contributors/
- Awesome list: https://github.com/mntnr/awesome-contributing
CONTRIBUTING
is a file that explains how people should contribute, and that can help verify people are submitting well-formed pull requests and opening useful issues.
- Help: https://help.github.com/articles/creating-an-issue-template-for-your-repository/
- Awesome list: https://github.com/devspace/awesome-github-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.
https://blog.github.com/2018-01-25-multiple-issue-and-pull-request-templates/
To add multiple issue templates to a repository create an ISSUE_TEMPLATE/
directory in your project root. Within that ISSUE_TEMPLATE/
directory you can create as many issue templates as you need, for example ISSUE_TEMPLATE/bugs.md
.
GitHub uses Jekyll to compile static sites for hosting through its GitHub Pages service. Jekyll configuration is read directly from the repository.
The following files and directories are used by Jekyll:
_config.yml
_drafts/
_includes/
_layouts/
_posts/
_data/
_sass/
_site/
.jekyll-metadata
index
All other files in the repository are included in the generated site without additional processing.
https://help.github.com/articles/adding-a-license-to-a-repository/
LICENSE
is a file that explains the legal licensing, such as any rights, any restrictions, any regulations, 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.
- Help: https://help.github.com/articles/creating-a-pull-request-template-for-your-repository/
- Awesome list: https://github.com/devspace/awesome-github-templates
When you add a PULL_REQUEST_TEMPLATE
file to your repository, project contributors will automatically see the template's contents in the pull request body. Templates customize and standardize the information you'd like included when contributors create pull requests.
https://blog.github.com/2018-01-25-multiple-issue-and-pull-request-templates/
You can create a PULL_REQUEST_TEMPLATE/
subdirectory in any of the supported folders to contain multiple pull request templates. Use the template query parameter to specify the template that will automatically fill the pull request body. For more information, see "About automation for issues and pull requests with query parameters."
- Help: https://help.github.com/articles/about-readmes/
- Awesome list: https://github.com/matiassingers/awesome-readme
README
is a file that explains your project, what it does, why it is useful, etc. The README
file is often the first item a visitor will see when visiting your repository. GitHub will recognize and automatically surface your README
to repository visitors.
SECURITY
describes your project's security policies, including a list of versions that are currently being maintained with security updates. It also gives instructions on how your users can submit a report of a vulnerability. If you provide a SECURITY
file, it will appear under the "Policy" link on the "Security" tab of your repository.