← notes

Eight community health files, and how GitHub resolves them

May 31, 2019

Collect the eight community health files a new repository should start with, and learn how GitHub actually resolves them.

README.md, CONTRIBUTING.md, CODE_OF_CONDUCT.md, SUPPORT.md, ISSUE_TEMPLATE.md, PULL_REQUEST_TEMPLATE.md, LICENSE.md, COPYING.md. The value is that each is wired into a specific GitHub surface, and the wiring is genuinely obscure.

Each file can live in the repository root, in .github/, or in docs/, resolved in a defined order. More usefully, an organisation can have a .github repository whose files act as defaults for every repo in the org lacking its own, which means a fifty-repo organisation does not need fifty copies of a code of conduct, which is what most of them have.

ISSUE_TEMPLATE.md as a single file is the older form, superseded by .github/ISSUE_TEMPLATE/*.yml issue forms that render as structured fields rather than markdown comments people delete. LICENSE.md versus COPYING.md matters for licence auto-detection, which matches filenames and contents against known texts, so an unusual filename or a modified clause shows as unrecognised.

Honestly, about half of these change behaviour and half are signals, and it is useful to know which is which.