Skip to content

Release Procedure

Jump to bottom
Alex Hübner edited this page Jan 29, 2024 · 56 revisions

Introduction

This document describes the release procedure for AncientMetagenomeDir. Releases are made periodically (~every three months) on the first day of a given month. Names of releases are derived from this wiki page.

⚠️ this release procedure currently requires knowledge of command-line git and admin privileges, however this maybe made automatic using Github Actions in the future.

Preparation

Clone (or pull, if already cloned) the 'data-frozen' master (typically when a given release milestone is at 100%).

git clone https://github.com/SPAAM-workshop/AncientMetagenomeDir.git

Change into the pulled directory

cd AncientMetagenomeDir

⚠️ if you are pulling (rather than cloning), make sure you're on the master branch.

Run through the pre-release checks by running the following script

Rscript assets/analysis/prerelease-validation-crosstable.R  ancientsinglegenome-hostassociated/samples/ancientsinglegenome-hostassociated_samples.tsv ancientsinglegenome-hostassociated/libraries/ancientsinglegenome-hostassociated_libraries.tsv ancientsinglegenome-hostassociated/conflicts.csv
Rscript assets/analysis/prerelease-validation-crosstable.R  ancientmetagenome-hostassociated/samples/ancientmetagenome-hostassociated_samples.tsv ancientmetagenome-hostassociated/libraries/ancientmetagenome-hostassociated_libraries.tsv ancientmetagenome-hostassociated/conflicts.csv
Rscript assets/analysis/prerelease-validation-crosstable.R  ancientmetagenome-environmental/samples/ancientmetagenome-environmental_samples.tsv ancientmetagenome-environmental/libraries/ancientmetagenome-environmental_libraries.tsv ancientmetagenome-environmental/conflicts.csv

Check for any rows that have unexpected numbers of NAs that indicate a bad joining (tip: normally filtering for NA on the publication_doi column will find anything that is dodgy; in most cases it's because the sample_name columns between samples and libraries are not exactly the same).

Once checked and fix, you can clean up with

rm -r ancient*/conflicts*

Next we do another check by opening the following file and runnning each step manually in R, and running through each line step by step.

Make sure to read through the comments for certain exceptions.

assets/analysis/prerelease-validation-withintable.R

ℹ️ this has not been automated as often trying to work out why errors occur requires manual curation.

Once no errors are found, you can run the following script to get the release statement.

⚠️ make sure to update the version tags at the top of the R script before running!

Rscript assets/analysis/release-stats-statement-generator.R

(I would suggest double checking the numbers, but they should make sense).

Release Preparation

Update the Latest Release badge on ~line 6 of the README file, e.g.

[![latest_release](https://img.shields.io/badge/Latest%20Release-v20.09-yellow)](https://github.com/SPAAM-workshop/AncientMetagenomeDir/releases)

to

[![latest_release](https://img.shields.io/badge/Latest%20Release-v20.12-yellow)](https://github.com/SPAAM-workshop/AncientMetagenomeDir/releases)

Also remove the [Unreleased] tag in the CHANGELOG.md next to the corresponding release, on ~line 6. e.g.

## Release v20.12: Ancient City of Nessebar [Unreleased]

to

## Release v20.12: Ancient City of Nessebar

Push these changes to master

git add README.md CHANGELOG.md assets/analysis/release-stats-statement-generator.R
git commit -m "Update versions for release"
git push

Once pushed, monitor the GitHub repository for the GitHub Actions check on master until it goes green against the latest commit from 'actions-user' - this is to ensure you have the final stats images from the auto-updater.

Once you get the tick, pull the repository one last time:

git pull

Run the following command to make a .zip archive containing just the table directories (and contents, changelog, final images, and README(s)).

VERSION=23.03.0
zip -r AncientMetagenomeDir_v"$VERSION".zip ancient*/ CHANGELOG.md README.md assets/images/figures/* assets/documentation/*

⚠️ make sure to update the version in the ZIP name!

Make Release

Go to the GitHub releases page, press 'Draft New Release'.

Also have in a separate tab the AncientMetagenomeDir Pull Requests page

Fill in the release information as in this example:

⚠️ Do not tick 'set as latest'! This will break the version pulling and parsing when running AMDirT locally!

Tag: v20.09

Release Title: v20.09: Ancient Ksour of Ouadane

Describe this release: A release description with some basic stats (number of new publications, new samples, and sample totals), the full changelog of this release, and also the description for the corresponding UNESCO information page of the corresponding release name (see other releases as examples). Also include the github handles of all the people who made PRs, and also reviewed them (open each closed PR included this release, to get both lists of people).

💡 You can use the script assets/utility/release_stats_statement_generator.R to generate the statistics statement for you.

Upload the ZIP file in the 'Attach binaries' section.

Then press publish release!

Clean up

  1. Go to the Zenodo release, press the DOI badge of the latest release (above the 'Versions' panel on the right-hand side bar), and copy the 'Markdown' code.

  2. Go back to the the releases page, and edit the release to add the markdown DOI code at the top of the description and press update.

  3. Back on in your cloned repository, delete the ZIP file.

    rm Ancient*.zip

  4. Now re-edit the CHANGELOG to add the next release from the release list above the just made release, and add [Unreleased], including all the subheadings (new publications, corrects etc.). E.g.

    # Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project follows to [Calendar Versioning](https://calver.org/).

## v21.03: Torn of Provins [Unreleased]

### Added

#### Ancient Metagenome: Host Associated

#### Ancient Single Genome: Host Associated

#### Ancient Metagenome: Environmental
    
### Changed

### Removed

## v20.12: Ancient City of Nessebar
<...>

  5. Push changes

    git add README.md
git commit -m "Update release info"
git push

License: CC BY 4.0

Clone this wiki locally