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.