Minimum standards for a github repository

Steve Simon


Using a github repository is new to me, and I need to document some things that may be obvious to more experienced programmers. Here are, as far as I understand it, the minimal documentation standards for a github repository.

The first thing you need is a name for your repository. All my repositories (so far) are public, so I want a reasonably descriptive name. The githum site playfully suggests names like “furry-parakeet” and I will stick by that convention. Most of my repositories (so far) are two or three simple words connected with dashes (understanding-lasso, sparse-matrices).

If you use github, they will tell you that every repository should have three files:

  1. .gitignore

I’m not thrilled about including the third file because it has no extension, but it’s a mistake for a beginner like me to deviate from well established standards.

The .gitignore file tells git that there are certain types of files that might exist on your local computer but which are not needed or wanted in the repository. This is important, because you�don’t want a repository that is excessively cluttered. Here are the files that I put in .gitignore.

Many people who peruse your github repository will look for and expect to see a file. What should go in this file? It depends, but the general recommendation is to give genereal instructions on what your visitors need to have in order to use the code in your repository. Here’s a draft boilerplate of what I have written, though I expect I will change this to the special needs and requirements of an individual repository.

This is a single file stand-alone application using R Markdown.

It was run and tested using RStudio and the knitr package.

Use the file with the .Rmd extension as input, or examine the file with the .html extension to see what the output is like.

This application does not need any special files beyond the ones listed above.

You need to decide what license you want for your repository. If you are making your code publicly available, you are already committed to a high level of sharing, so you should consider a fairly liberal license. I decided on the Creative Commons Public Domain license. It’s a bit more liberal than what I have for the rest of my blog and web site, but I’m fine with that.

You can find an earlier version of this page on my blog.