---
aliases:
- /2017/02/publish-research-software-github
categories:
- git
- github
- openscience
date: 2017-02-01 18:00
layout: post
slug: publish-research-software-github
title: How to publish your research software to Github

---

* Do you want to make your research software available publicly on Github?
* Has your reviewer asked to publish the code described in your paper?
* Would you like to collaborate on your research software with other people, either local or remote?

Nowadays many journals require that the software used to produce results described in a scientific paper be made available publicly
for other peers to be able to reproduce the results or even just explore the analysis more in detail.

The most popular platform is [Github](http://github.com), it allows to create a homepage for your software, keep track of any future code change and allows people to report issues or contribute patches easily.

I'll assume familiarity with working from the command line.

## Prepare your software for publication

First it is necessary to make sure your code is all inside a single root folder (with any number of subfolders), then cleanup any build artifact, data or executable present in your tree of folders.
Ideally you should only have the source code and documentation.
If you have small datasets (<10MB total) it is convenient to store them inside the repository, otherwise better host them on dedicated free services like [Figshare](http://figshare.com).

You should cleanup the build and installation process for your code, if any, and ideally you should structure your code in a standard format to ease adoption, for example using a project template generated by [Cookiecutter](https://github.com/audreyr/cookiecutter).

You should create a `README.md` file in the root folder of your project, this is very important because it will be transformed into HTML and displayed in the homepage of your software project. Here you should use the Markdown formatting language, see [a Markdown cheatsheet on Github](https://help.github.com/articles/basic-writing-and-formatting-syntax/), to explain:

* short description of your software
* build/usage requirements for your process
* installation instructions (and point to another file `INSTALL.md` for more details)
* quickstart section
* link to usage examples
* link to your paper about the project
* list of developers
* optionally: how users can get support (i.e. a mailing list)

Finally you should choose a license, otherwise even if the project is public, nobody is allowed to modify and re-use it legally.
Create a `LICENSE` file in the root of folder tree and paste the content of the license. I recommend MIT license which is very permissive and simple: <https://choosealicense.com/licenses/mit/>

## Create an account on Github

Second step is to create an account on Github: this just requires a username, email and password, choose your username carefully because it will become the
root internet address of all your software projects, i.e. `https://github.com/username/software-name`.

A Github account is free and allows any number of public software projects, private repositories are generally available only on paid account, however
who has a `.edu` email address can apply for unlimited private repositories by applying for the [academic discount](https://education.github.com/discount_requests/new).


## Create a repository on Github

Github hosts software inside a version control system, `git`, so that it stores the complete history of all the incremental changes over time and allows to easily
recover previous versions of the software. Each software project is stored in a repository, which includes both the current version and all previous versions of the software.`git` is a more modern alternative to `subversion`.

First you need to create a repository on Github: authenticate on Github.com and click on the "New Repository" button, choose a name for your software project and leave all other options as default.

## Publish your software on Github

Make sure that the `git` command line tool is available on the machine where your code is stored, install it from your package manager or see [installation instructions on the git website](https://git-scm.com/downloads).

Finally you can follow the instructions on the repository homepage `https://github.com/username/software-name` in the section **..or create a new repository on the command line**,
make sure you are in the root folder of your repository and follow this steps:

Turn the current folder into a `git` repository:

	git init

Add recursively all files and folders, otherwise specify filenames or wildcard to pick only some, **be careful not to accidentally upload sensitive content like passwords**:

	git add *

Store into the repository a first version of the software:

	git commit -m "first version of the software"

Tell `git` the address of the remote repository on Github (make sure to use your username and the name you chose for your software project):

	git remote add origin https://github.com/username/software-name

Upload the software to Github:

	git push -u origin master

You can then check in your browser that all the code you meant to publish is available on Github

## Update your software

Whenever in the future you need to make modifications to the software:

* edit the files
* `git add filename1 filename2` to prepare them for commit
* `git commit -m "bugfix"` create a version in the history with a explanatory commit message
* `git push` to publish to Github

For more details on `git`, check the [Software Carpentry lessons](https://swcarpentry.github.io/git-novice/).