Best Practice Open Source Repo Setup

swyx 2020-01-19

I often make the joke that GitHub doesn’t do enough to encourage community standards:

Why Standards Are Important

These standards aren’t just made up for shits and giggles. They genuinely help the open source community work better together:

Descriptions are important as short oneliners for people to understand what your repo is for.
Readme’s are important for people to understand what your repo does and how to use it. I have strong views here!
Codes of Conduct help define what is permissible behavior in your community. And yes, every open source repo is a community.
CONTRIBUTING.md welcomes potential contributors and gives them information they need to get started. This is particularly prone to unhelpful boilerplate - more thoughtful customization would help contributors. Here is a great example from Kent C. Dodds.
Licenses are important so people know what they can or cannot do with your code. GitHub’s default is no license - this is bad, because without a license, some people are technically not even allowed to LOOK at your code.
Issue and PR templates help maintainers ask basic checklist questions to improve the quality of issues and contributions (and waste less time on back-and-forth).
.gitignore is important because people often forget to ignore their node_modules and .DS_Store and other non-core folders. Consider also adding .vscode
(optional) - CHANGELOG.md, .nvmrc, .gitattributes, CODEOWNERS, .editorconfig, .prettierrc, SUPPORT

This isn’t a huge list of stuff, but it can be a bit of a drag to set all this up manually especially if you operate Open Source by Default. Most of my own repos don’t even meet these standards because it is such a drag to set them up.

In GitHub, you can check what you’re missing by going to the More > Insights > Community page on your repo:

And it has nice UI prompts to help you add things if you are missing them.

Automate It

Here are some tools and bash scripts to run thanks to my friends Tierney and Phil:

npx license mit > LICENSE.md  # initialize your license
npx gitignore node  # initialize your gitignore
npx covgen YOUR_EMAIL_ADDRESS # code of conduct
git init # initialize git
npm init -y # initialize package.json, accept all defaults

You can inline this into a oneliner bash command: npx license mit > http://LICENSE.md && npx gitignore node && npx covgen YOUR_EMAIL_ADDRESS (adding in git and npm init if you wish).

Note that in order to use npm init -y with decent defaults, you should set them:

npm set init.author.name "Your name"
npm set init.author.email "your@email.com"
npm set init.author.url "https://your-url.com"
npm set init.license "MIT"
npm set init.version "1.0.0"

Kyle and Phil put this in bash scripts to add a few other steps all in a single init_repo command:

init_repo() {
  # delete any of the below per your preference
  mkcd $1
  git init
  npm init -y
  npx license $(npm get init.license) -o "$(npm get init.author.name)" > LICENSE
  npx gitignore node
  npx covgen "$(npm get init.author.email)"
  git add -A
  git commit -m "Initial commit"
}

Of course, these steps don’t take care of ALL the standards listed above - so far the only tool I have come across that handles them all is CGX

This generates (according to their README):

### Github, Gitlab and Bitbucket
* License 
  - MIT
  - ISC
  - Apache 2.0
  - BSD 2-Clause
  - GPLv3
* Changelog
* Contributing
* Readme
* Todo
* Code of Conduct

### Github specific
* Bug report (issue)
* Security vulnerability report
* Feature request (issue)
* Pull request template
* All files at once

### Gitlab specific
* CI template
* Bug (issue)
* Feature proposal (issue)
* Merge request
* All files at once

### Bitbucket specific
* In future versions

Make Your Own

Isaac Schleuter, npm founder, chimed in that you can actually make your own and it can be invoked via the npm init command! TIL!

Best Practice Open Source Repo Setup

Why Standards Are Important

Automate It

Make Your Own

Other Useful Tools and Reads

Latest Posts