Practical 6: Archiving a release

Activity Overview

Goal: Create a release

When should you create a release?

In general, you should create a release when you are sharing the results of a specific version of your code, for example:

  • If you are creating a presentation or poster for a conference, create a release for the version of the code that created the results you’re sharing, and cite the DOI in your presentation/on your poster.
  • If you are submitting a journal article (and a preprint), snapshot, release, and archive your code. Cite the version in your paper when you reference the use of your code. You can also add something like this to the final acknowledgements/notes section: “The results and figures in this paper were generated with <Project-name> v0.1.0, archived at <zenodo_link_here>, <DOI>.”
  • If you are resubmitting a paper (and updated pre-print) after review, if you’ve made any changes to the code, re-release it and update the references/DOI in your paper.

Stage 1: Preparation

Preparing for a tagged release: adding a License

For this example project, we’re going to use the MIT license. This is easy to add through the online interface. Make sure you’ve completed your local git cycle (so git status shows no changes), then swap over to your repository page on GitHub. In the navigation bar above the table of your files in the repository, click “+” and select “Create new file”. In the “Name your file” input textbox, type LICENSE. When you finish, a button should appear below the text input box, with the option to “Choose a license template”. Find the MIT license in the sidebar, check that your name and the year are correct, and hit “Review and Submit”. You can then commit the changes. Make sure to then run a git pull origin main from within your local repository.

Preparing for a tagged release: updating your README.md

The README.md file is likely the first thing (and possibly the only thing!) that people browsing your code will read. It’s important to make it useful, and share critical information here! We previously added some very basic information, but let’s flesh out the README a little with some more useful details.

Here’s a simple template you can copy into your README file. Replace <PACKAGE_NAME> with the text-and-underscore-only name of the folder inside src/, replace <REPO_NAME> with the overall project folder/git repository name, and include your GitHub username in place of <USER_NAME>. Replace <LICENSE> with "MIT". You should already have added the title and brief description of your project. Fill in your details under “Author”. On research projects, you’re likely to have more than one author, or to have people as “Contributors” if they helped with some portion of the code.

We’re also going to include a badge in the README, that once you release with Zenodo, will show the correct DOI.

(Credit for the Zenodo badge workaround goes to the GitHub member seignovert)

  1. Visit https://api.github.com/repos/<USER_NAME>/<REPO_NAME>, replacing <USER_NAME> and <REPO_NAME> with your GitHub username, and the GitHub repository name respectively.
  2. Find the first entry, "id", and copy the number. This is your <GITHUB_ID>
  3. Replace <GITHUB_ID> in [![DOI](https://zenodo.org/badge/<GITHUB_ID>.svg)](https://zenodo.org/badge/latestdoi/<GITHUB_ID>) in the template below, so it looks something like: [![DOI](https://zenodo.org/badge/123456789.svg)](https://zenodo.org/badge/latestdoi/123456789)
  4. Save and commit the README; do not worry that the image link is currently broken.
# <Project title here>

<Brief few-sentence description here>

[![DOI](https://zenodo.org/badge/<GITHUB_ID>.svg)](https://zenodo.org/badge/latestdoi/<GITHUB_ID>)

## Installation instructions

You can use pip to install the package <PACKAGE_NAME> to run the scripts in this project:

Install the most recent development version (may not be stable):

```bash
pip install <PACKAGE_NAME>@git+https://github.com/<USER_NAME>/<REPO_NAME>
```

Or install a specific version (version 0.1.0 in this example; please check the releases page):

```bash
pip install https://github.com/<USER_NAME>/<REPO_NAME>/archive/refs/tags/v0.1.0.tar.gz

# or

pip install <PACKAGE_NAME>@git+https://github.com/m<USER_NAME>/<REPO_NAME>@v0.1.0
```

## Author

*Your name, institution, OrcidID*

## Citation instructions

Please use the suggested citation in the sidebar (under "Cite this repository"), or view the CITATION.cff file.

## License

<REPO_NAME> and <PACKAGE_NAME> are distributed under the <LICENSE> license. See [`LICENSE`](LICENSE.md) for more details.

Preparing for a tagged release: creating or updating your CITATION.cff

Now we’re going to create our citation file. You’ll already have an empty CITATION.cff file in your repository from the initial folder set-up.

You can either copy the minimal example below and modify it to suit, or use the cff generator form.

Here’s a basic example provided by Zenodo:

cff-version: 1.2.0
title: "Memory bus simulation scripts"
version: 1.8.0
license: "MIT"
type: software
abstract: "These are the scripts used to simulate a memory bus"
message: "If you use this software, please cite it as below."
authors:
  - given-names: Josiah
    family-names: Carberry
    affiliation: Brown University
    orcid: "https://orcid.org/0000-0002-1825-0097"
keywords:
  - computer science
  - psychoceramics
  - journaling filesystems

Make sure to modify the version number to match your upcoming release number.

Preparing for a tagged release: update your pyproject.toml

Update your Python configuration file to make the version number to match your upcoming release number. Make sure it contains all the dependencies directly loaded in your Python package files (so in the .py files inside src/).

Preparing for a tagged release: export your exact environment for reproducibility

If you have gone down the path of a single folder project (so all your notebooks and analysis scripts are also in this same directory), it is time to export your exact conda environment. From inside your active Conda environment, run:

conda env export > env-record.yml # from inside the activated env

This record .yml won’t be useful for reusability as it likely will flag a lot of errors if you try to use it to recreate your environment on another platform, but it is very useful for reproducibility, and will allow you to track down the possible sources any weird inconsistencies in the future by knowing the exact versions of every package.

Preparing for a tagged release: rerunning your tests

It’s a good idea to run your test suite at this point just to make sure everything is working correctly.

Stage 2: Create release

Setting Up Zenodo Integration

Step 1: Create Zenodo Account

  1. Go to zenodo.org
  2. Sign up with your GitHub account
  3. Authorize Zenodo to access your repositories

Step 2: Enable Repository

  1. Go to your Zenodo GitHub settings
  2. Find your repository
  3. Toggle the switch to “ON”

Tag your release

  1. Go to your GitHub repository
  2. Click on “Releases” (right sidebar)
  3. Click “Draft a new release”
  4. Click “Choose a tag” and type v0.1.0 in the text box, then select “+ Create new tag: v0.1.0 on publish”
  5. Add v0.1.0 into the text box “Release title”
  6. Click “Generate release notes”
  7. Add in some additional information (see release notes template below)
  8. Scroll down and click “Publish release”

Release note template

## What's New

- Added user authentication system
- Implemented dark mode theme
- New API endpoints for data export

## Bug Fixes

- Fixed memory leak in background processing
- Resolved CSS styling issues on mobile

## Breaking Changes

- Changed API response format for /users endpoint
- Removed deprecated `legacy_mode` parameter

Check that everything worked

On your main repository page:

  • Your README should now have a correctly formatted badge with a DOI, linking to your Zenodo repository;
  • There should now be a section on the sidebar linking to your release, your license, and a “Cite this repository” shortcut.
Well done! You’ve created your first release!

Now you have a citable piece of software with a DOI. It’s a good idea to now go back to your CITATION.cff file and add in your DOI there!