This past weekend I had the pleasant experience of migrating my software KARDIA form its old home at the SourceForge repository to GitHub. Although the clearest benefit from this migration is the possibility to easier collaborate with other programers for the future development of the software, there are several other sweet candies that came along…
First of all, it looks great! With less than an hour of markdown editing, the README file, that is open by default when you visit the landing page, became KARDIA’s tutorial, with a detailed description of all the main functions, including screenshots from the program’s graphical interface.
Second, with the perfect integration between GitHub and Zenodo, in less than five minutes I had uploaded the latest release of the software code to the Zenodo repository, which instantly assigned a DOI, making the code itself a citable research object!
GitHub is ultimately a collaboration platform for programers who wish to work together for the co-development of open source software, but is also a place for end users to request features, report bugs and offer their feedback. Another cool feature is the wiki option, which makes it possible for programmers and users to collaborate for the development of instructional material and detailed use cases.
GitHub has been around for about 10 years and is considered the state of the art in git-based software development platforms. My first impressions from this new workflow for developing and sharing open source scientific software have been so positive that I strongly recommend it to any colleagues who think that their software code could be useful to others.
Here are a few steps to get you going:
- Document properly your code using function descriptions, inline comments and intuitive variable names.
- Install the git version control system: https://git-scm.com.
- Create a GitHub account and add a new repository.
- Use terminal commands (for this you will have to do some reading first, the documentation you will find here will come in handy), or some third-party interface to upload your local repository to GitHub (I used GitHub Desktop).
- After you upload your local repository to GitHub make sure you include a license file and a readme file. GitHub makes it easy by adding these two files automatically upon request. The only thing you have to do is to edit your readme file to introduce your software and its functions to the world. You will need to edit the readme file with Markdown language. If you haven’t done that before use another file as a reference. For example you can look at the markdown code of KARDIA’s readme file that uses headings, subheadings, references with hyperlinks, and figures. Here is the raw code and here is the formatted result.
- Create a Zenodo account if you do not already have one.
- Once you are logged in to your Zenodo account, follow the simple steps described here and in less than five minutes you will have your software code automatically uploaded to Zenodo with a DOI you can add to your CV and a beautiful badge like this one!
If you feel that your software also deserves to be reviewed and published as a journal paper with its own DOI, one great option seems to be to submit your work to The Journal of Open Source Software. KARDIA was published back in 2010 so I did not have the opportunity to test this process but from what I have read at the author guidelines everything looks pretty straightforward once your code is properly documented and uploaded to GitHub. I will definitely give it a try in the future.
Finally, make sure to share your new repository with your colleagues and with existing users of your software. And when all is said and done, sit back, relax and celebrate your contribution to make science more open and collaborative with a nice cup of coffee…
