Skip to Main Content

Research Software: Designing for Publication and Reproducibility

How to prepare scholarly code for submission to journals or repositories.

Selecting A Repository

We recommend publishing your code in an open-source repository that will do the following:

  • Assign a DOI (digital object identifier), a persistent link to your software that's more permanent than a URL, so your software can be cited and remain accessible
  • Reliably guarantee long-term preservation of and access to your software
    • Provide information on their funding model and financial sustainability and/or details on what will happen to the contents of the repository if they cease operations
  • Allow versioning of your work
  • Ideally, provide software-specific metadata and browsing functionality

Some journals may have their own requirements for how you publish and provide access to your software; for example, they may ask you to place your work in a repository that permits anonymous reviewer access. 

It's also possible that you will want to put data in one repository--perhaps because of its size, or because a certain data repository is standard within your discipline--while storing code elsewhere. Thankfully, the DOI system makes it possible to create canonical links between all of the pieces of your scholarly project.

I Put My Software on GitHub, Isn't That Enough?

That's great! But no.

GitHub, and similar version-controlled code-sharing sites like GitLab and BitBucket, are not designed for preservation; they're ultimately commercial products. Microsoft makes no promises of ensuring all GitHub projects stay useable and accessible in the long term. GitHub vanishing into thin air might seem unthinkable now, but recall that Google sunsetted its GitHub-style code hosting service Google Code, in 2016. Even if GitHub doesn't disappear, it might change its URL structure in a way that breaks links (which happened when it switched from github.com to github.io, as described in this blog post) , or the privileges for paid vs. free users. Also, developers in countries that face US sanctions or have governments that impose internet censorship may have limited access to GitHub.

In many cases, GitHub (or GitLab, or BitBucket, or another similar site) may be where you and most of your users interact with the software. However, a stable copy can and should live in the longer term in a designated repository that can assign a DOI to your work.

 

Resources