Overview

Teaching: 15 min
Exercises: 20 min

Questions

• Why publish code?

• What does ‘publish’ even mean?

• Ok, so how and where can I publish my code?

Objectives

• Review the FAIR principles for software publishing

• Be able to publish code to Zenodo and recieve a DOI

• Be able to register your code on ASCL.net

Publishing code

Publishing your software will allow you to share your work with a larger audience. Having your software shared online will increase the visibility of your work, which can lead to greater recognition of your work through software citation.

Developing or contributing to a software package that is widely used is another way that your effort can be recognized and can be used to strengthen a grant, scholarship, or job application.

Any code that you use as part of your research should be considered for publication. Depending on the size of the codebase, the intended audience, and intended use of the code, you will want to put a different amount of effort into publishing and publicizing your work.

At the very least, you should keep all your work under version control, and have these repositories “backed up” or “mirrored” online to guard against data loss. GitHub, GitLab, and Bitbucket are great places to do this, and so long as you don’t set your repository to be private, then you have published your work.

Once you have code that you are happy to share among collaborators you should consider publishing this code.

What do we mean by publishing? From least to greatest effort, any of the following could be considered as a definition for publishing code:

1. Copying a version of your code to a public website for others to find and use,
2. Making your version control repository (github, gitlab, bitbucket) public so that others can use and reuse your code,
3. Uploading your code to a repository such a pypi.org so that others can easily download/install your software,
4. Archiving a version of your code to a doi minting / storage service such as zenodo.org, or figshare,
5. Registering your code on a site such as ascl.net so that others can find your code,
6. Writing a paper describing an application of your code and submitting for peer review in a science focused journal such as PASA or MNRAS,
7. Writing a companion paper that describes your code and submitting the paper and code for peer review in a software focused journal such as A&C, JOSS, RNAAS, or SoftwareX.

From the descriptions above you can see that the different options have slightly different intentions and audiences. We can take an lead from FAIR principles for data, and apply these principles to code.

Findable

Make code findable by creating a persistent identifier (eg doi) and including metadata. On pypi/zenodo/github you can use tags or topics to identify the software language but also the area of research or methodology that is being used. This makes it easier for people to find code that will suit their needs.

Accessible

Make code accessible by providing source code, install instructions, and documentation. Testing code on a range of platforms will also increase the accessibility of the code.

Interoperable

Use standard project templates, coding styles and idioms, and a modular design to allow your code to be used as part of a larger workflow or as a component of another product. This interoperability is useful for others, but will also make it easier for you to build on your own existing solutions.

Reusable

Make code reusable by providing a license, and indicating how people should acknowledge use of your work.

Reasons not to publish

The following are often given as reasons not to publish code:

Obtaining a doi from Zenodo.org

You have a piece of code on github, but it is changing over time, and you would like to provide a link to a particular version of the code. This is important for reproducibility of your research work, both for yourself and others.

The Zenodo repository provides a safe, trusted, and citable place to host your code. Zenodo is primarily focused on the storage of data, but this includes: documentation, papers, posters, raw or processed data, source code, and compiled binaries. Zenodo will allow you to version your data but does not provide a version control system such as git. However, Zenodo and Github are friends so you can link them together to get the best of both worlds.

Sign up to Zenodo

You can create a new Zenodo account using an email address and password, or you can use your Github or ORCID accounts to login. Whatever you choose, you can still link your github/ORCID later and use them to sign in.

Create a new repository

Once signed in click on the upload button at the top of the page, and then on the next page click “New Upload”:

The following page will have a lot of details, some of which are mandatory, but most of which are either recommended or optional. Begin by downloading a .zip of your files from Github:

Once you have your zip file from GitHub, upload it to Zenodo, and then press the green “start upload” button and then start filling out the rest of the form. As the upload is progressing you can fill in the upload type (Software) and basic information.

Leave the DOI blank, but click the “reserve DOI” button so that you can know what the final DOI will be.

Fill in the remainder of the form and then press “save” at the top of the page, this will make a draft of your repository that you can come back to later and update. When you are finally happy with all the details you can press ‘publish’.

Once your upload has been published you should navigate to the published repository in your uploads list, and select it.

The above example is for the Aegean source finding software. You can see the DOI badge with the full DOI, a link to supplementary material, and the license. If you click the DOI badge you’ll get a new pane that shows you how to embed this information into a markdown file such as your README.md that you have on your github page!

Below this panel you can also see a box that allows people to cite your code. There is even a box that allows people to get the citation in any format that they need it.

You now have a version of your code which is archived on Zenodo and will not change. If you want to update the archive with new versions of the code, Zenodo has the capacity to do this, and will mint a new doi for each version. It is recommended that you don’t make a new doi for every small change you make to your code. A new version for each major or minor version change would be appropriate, or when you have published work that used a particular major/minor/patch version of the code.

Sadly Zenodo is not indexed by ADS so you can’t track citations very well from here. However, ASCL.net is indexed by ADS so we can register our code on there.

Registering your code on ascl.net

In this section we’ll make an entry in the Astrophysics Source Code Library (ASCL.net), which is indexed by ADS, and can help you gain an audience, and track citations.

Submit a code to ASCL

Go to the “submit a code” page here.

The page asks for a title, credit (authors/contributors), abstract, and a site list for the code.

The site list should be a list of links to places where people can obtain the code. I highly recommend that you put a link to both your Github and Zenodo repositories. If the code was described in a paper you can put that in the “Preferred Citation Method” section.

ASCL.net does not store your code. No one will vet the quality of your code. ASCL.net is simply a place to register that some code exists and that you’d like to be acknowledged for creating/contributing. ASCL.net is indexed by ADS so it will get a bibcode in ADS, which can then be used to generate a bibtex entry for people to use when citing your code. Another goal of ASCL.net is to make it easier for people to find your code in the first place. If you haven’t explored the code available here I recommend that you do so now – there are some gems.

Where else?

Of course we have skipped the most logical place for us to publish our python code - pypi.org! In the next episode we’ll cover just that.

Key Points

• You deserve credit for all the work you do

• Publishing code can help you increase your publication/citation rate

• Publishing your code ‘pays forward’ the efforts of people who developed your dependencies