blog

SEAN K.H. LIAO

repo metadata

(Long lived) code is usually hosted in a repo somewhere. Sometimes that can be public, or maybe just shared with a few people (include your future self as one of those people). Now you need to add some metadata to your repo so people can understand / work better together (ie share common standards), and litter the root of your repo with a bunch of files.

README

Probably the first thing people see, note this document may also be copied into other places, such as documentation sites pkg.go.dev or container registries docker.io .

There are lots of ideas as to what should go in here, I think a short intro as to what it does, an example of what it's like to use the thing, and how to get started are the things I look for. Other sections such as contributing/license/architecture/... usually already have their own files.

badges

Because we need little blocks of color making a dozen requests every time you view the page and they have to fight with caching. At least they're good for at a glance and a consistent place to put third party links.

There are a lot of badges from a lot of places, ex shields.io

The common ones I see are:

Other ones include

LICENSE

The only file mandatory for making things public.

Should be something that tools such as SPDX can recognize.

CONTRIBUTING

Related to license, how to get setup to build, patch, and contribute upstream.

CODE_OF_CONDUCT

Related to contributing, how to interact with the "community"

templates for issues and prs

Related to contributing, Github/other code host specific, templates to follow so maintainers don't have to chase you to get more info.

CHANGELOG

No standard format exists.

Single file or a directory of files. Handwritten ones are good especically if they highlight the important bits, but are tiresome to write. Worth it for big projects with infrequent releases. Generated ones are noisy but maybe good enough for continuous releases and if you enforce good commit messages.

SECURITY

Who do you call if you found a critical bug?

Need somewhere to put retractions/CVEs...

semver

semver

Related to releasing, use semver to communicate stability of public interfaces / project maturity.

tooling

Because each repo is a special snowflake, we need more files to tell our tools how it should work in this repo.

.editorconfig

Some ini-like file that reduces the editor specific files a little bit. Right now supports spacing/tabs. Probably needs to support a lot more for it not to be yet another file.

.gitattributes

Tell git how to treat different files, add optional filters.

.*ignore

Tell our tools to ignore other files that just have to be there for other purposes.

build configuration

This is usually a good thing, having a documented, repeatable way of building code. Also includes the CI/CD configuration that is unfortunately not really portable across platforms.