Add software release checklist

[nielsdrost]

@rvanharen made a checklist for releasing software. We should add it to the guide somewhere, probably https://guide.esciencecenter.nl/best_practices/releases.html

• Changelog available and up to date
• CITATION.cff available
• .zenodo.json available
• CONTRIBUTING.md available
• Integration with readthedocs
• Intergration with CI
• MANIFEST.in available
• README available
• tests passing
• all contributors in setup.py, CITATION.cff, .zenodo.json
• Update version numbering in setup.py, CITATION.cff
• pypi doesn't like markdown, convert README in rst
• enable integration with 3rd party services, codecov, zenodo, travis
• Create actual realease on github
• Update doi in CITATION.cff and README from the one you find in Zenodo
• Create PyPI release: see https://realpython.com/pypi-publish-python-package/
• Create a Conda release

[jspaaks]

At the moment, including the versioned doi in your CFF creates a chicken and egg problem (see discussions here). As a workaround, I recommend using the conceptDOI.

[jmaassen]

This is a bit python specific here and there? We should split general recommendations from language specific ones (or just have the entire list for different languages).

[rvanharen]

Yes, we should generalize it a bit, point to documentation where we can, etc.

[LourensVeen]

FWIW, here's the latest version of my release procedure, in case it contains anything useful: https://muscle3.readthedocs.io/en/latest/releasing.html

I'm still missing a CITATION.cff in my repos, and I'm not sure whether a .zenodo.json is needed? I seem to be getting DOIs just fine...

[rvanharen]

@LourensVeen The .zenodo.json is to get the authors/affiliation/orcid automatically added to Zenodo. I see however that muscle3 has them set on Zenodo as well, did you add these manually?

[jspaaks]

indeed you get dois, but the metadata is inconsistent. A .zenodo.json file is needed. see here on how to get them https://guide.esciencecenter.nl/citable_software/making_software_citable.html

Maybe a more language agnostic recommendation is for people to include a For maintainers section in their READMEs, explicitly detailing their release process. Other people can then make PRs for that part of the README, as I just did for xenon https://github.com/xenon-middleware/xenon/pull/653

[bouweandela]

I would also be fine with having the entire checklist above in the Python chapter, having multiple checklists to check before doing a release leads to errors, exactly what you're trying to avoid by creating a checklist. Other language chapters can than add their own release checklist.

[sverhoeven]

By default Zenodo uses <GitHub organization>/<GitHub repo>: <GitHub release title> as title, the committers as authors and a generic open access license. These defaults can by overwritten by editing the entry on https://zenodo.org or by using .zenodo.json file to overwrite the defaults.

I mostly do a hybrid where I set the title and license in .zenodo.json, use the description of the GitHub release and correct the authors, references to software/publications on https://zenodo.org manually.

[bouweandela]

This would fit better in The Turing Way.