Making software citable

Digital Object Identifiers are globally unique identifiers which can point to any digital object, such as a version of a paper, a version of software etc. This has the advantage that it is unambigous and standardized. For papers, using DOIs is commonplace, and a DOI is usually provided by the publisher. For software, you can make your own DOI with Zenodo:

  1. You can tell people how to cite your software by including a CITATION.cff file in the root of your repository (You can read up on the rationale of CITATION.cff files in this blog). However, writing CITATION.cff files by hand is a bit tedious and error-prone, so instead go to https://citation-file-format.github.io/cff-initializer-javascript/ and fill in the provided web form.
  2. Make a Zenodo account and link it with your GitHub account as explained on guides.github.com/activities/citable-code.
  3. You can tell Zenodo what metadata you want to associate with the software by including a .zenodo.json file in the root of your repository, but writing that file by hand is also error-prone. Therefore it is advisable to just generate it from the CITATION.cff file. To do so, you'll need a command line tool cffconvert which you can install from PyPI by:

     pip install --user cffconvert
    
  4. Make sure that your CITATION.cff is valid YAML by copy-pasting the contents to http://www.yamllint.com/.
  5. Make sure that your CITATION.cff is valid CFF, by:

     # (in the repository's root directory)
     cffconvert --validate
    

    If the command does not return anything, that means the CFF is valid.

  6. Generate the .zenodo.json file using cffconvert as follows:

     cffconvert --ignore-suspect-keys --outputformat zenodo --outfile .zenodo.json
    
  7. On Zenodo, make sure to 'Flip the switch' to the on position on the GitHub repository that you want to make a release of.
  8. Go to your Github repository, use the Create a new release button to create a release on GitHub.
  9. Zenodo should automatically be notified and should make a snapshot copy of the current state of your repository (just one branch, without any history), and should also assign a persistent identifier (DOI) to that snapshot.

    when things don't work

    In case the GitHub-Zenodo integration does not work as expected, there are two places to go and look for information:

    1. On GitHub:
      • go to https://github.com/<org>/<repo>/
      • select Settings
      • select Webhooks
      • select select the Zenodo webhook (may require GitHub login)
      • scroll down to Recent deliveries
      • click on one of the listed deliveries for details on the request, the response, and to request redelivery.
    2. On Zenodo:
      • go to https://zenodo.org/account/settings/github/
      • select the repository that you want to see the diagnostic information of
      • click on one of the releases to see the Payload Zenodo received from GitHub, as well as the Metadata that Zenodo has associated with your release, or Errors if there were any.
  10. Use the DOI whenever you refer to your software, be it in papers, posters, or even tweets and blogs.

  11. Add the software's Zenodo badge to your repository's README.

results matching ""

    No results matching ""