Release Process

This page describes the release process in some detail. Getting a release out of the door without embarrassing oversights requires a bit more planning and care than one would like.

Timeline for a release and estimated time required

Form a release coordination team (6 months) (part of ET calls)
1. a release coordinator
2. a release coordinator assistant, who may be the release coordinator for the next release
3. the former release coordinator to help out
4. test runner(s) who will run the testsuites on the list of supported machines
5. example runner volunteer(s) for gallery examples
Come up with release timeline (by translating the last release timeline forward in time), see (5 months) (30 minutes), see https://docs.einsteintoolkit.org/et-docs/Release_Details#Schedule_for_ET_2020_05
1. Frequently remind participants of timeline (part of ET calls)
2. Begin discussions on the mailing list, reminding people to look at test cases, review patches etc. (5 minutes per week)
Choose features which are going to be included, and those which won't be included (4 months)
1. ask for review volunteers, assign tasks to people (part of ET calls) e.g. https://docs.einsteintoolkit.org/et-docs/Meeting_agenda#2020-09-10
2. create tickets for each proposed item on https://trac.einsteintoolkit.org eg. https://bitbucket.org/einsteintoolkit/tickets/issues/2416
3. Decide on a list of release-critical compute systems eg XSEDE, LCCF, DOE, PRACE: http://einsteintoolkit.org/testsuite_results/index.php
  1. get accounts for test runners
Drive review of thorns for code quality, documentation, test cases (continuously)
1. Include positively reviewed and voted on items in main ET repositories
2. Remove new features without reviewer or negatively reviewed from list of new features
3. Frequently remind participants of timeline
Start testing on release-critical compute systems (2 months) (30 minutes per week per cluster to compile, run, check, upload)
1. initially test to make sure clusters can still build code
2. test code as they become positively reviewed (code is present in master before final positive review)
3. report on test failures
4. assign found bugs to volunteers
Release preparation I (2 weeks)
1. Announce feature freeze based on currently positively reviewed components
2. Update einsteinttoolkit.bib with requested and suggested citations for all thorns in thorn list (10 minutes)
3. Collect list of new features, newsworthy items, and acknowledgements for release announcement on wiki (there’s a script in the wiki to help with this) (45 minutes)
4. Verify that gallery runs and example parfiles still work with new release (4 hours for all examples to compile, run, make plots)
5. Contact contributors and example runners about permanent (contributors) and one-off (example runners) inclusion in the ET author list (10 minutes of work per author to poke and prod them to respond)
6. Draft release announcement (1 hour)
  1. send to maintainers@einsteintoolkit.org for review re typos etc.
7. Announce release date publicly
Release preparation II (1 week), detailed list of items and partial scripts on https://docs.einsteintoolkit.org/et-docs/Release_Process#Two_weeks_before_the_release
1. Finalize announcement draft (1 hour)
  1. Send to maintainers@einsteintoolkit.org for review re typos etc.
2. Create Zenodo item (see link above) (1 hour)
  1. Send to maintainers@einsteintoolkit.org for review re typos etc.
3. Create release branch and tag for all ET codes (30 minutes)
4. Update version information in Makefile, the documentation tex files and Baikal documentation.tex file (15 minutes)
5. Regenerate all auto-generated files (30 minutes of work, plus time to wait for Kranc)
6. Update websites in a branch (2 hours)
  1. EinsteinToolkit.org
  2. CactusCode.org
  3. Simfactory.org
  4. CactusTutorial.ipynb
The release (0 days)
1. make all updated branches live (30 min)
2. announce on users@einsteintoolkit.org, news@cactuscode.org, userss@cactuscode.org (5 min)
3. http://hyperspace.uni-frankfurt.de/ based on previous release announcement (15 min)
4. update Wikipedia Cactus entry https://en.wikipedia.org/wiki/Cactus_Framework (5 min)
5. Run the testsuite using the release code on all supported machines (30 min per cluster)
6. Update https://docs.einsteintoolkit.org/et-docs/Release_Process with lessons learned (30 minutes)

Helpful tools and notes

This section collects a handful of useful commands that may become critical to guarantee the quality of the release. The descriptions below are quite technical and intended for the developers and maintainers only.

update developers.txt

Inside https://bitbucket.org/einsteintoolkit/www/src/master/ , you will find a developers.txt file, which needs to be updated with any new developers for this release. Any developers who helped with the last release but have not yet contributed code to the Toolkit need to be removed, and likewise any new folks who contributed to this release need to be added.

After updating, run

 developers.py

and

 zenodo.py

and commit the changes.

drafting Zenodo entry

Be sure to address this! https://bitbucket.org/einsteintoolkit/tickets/issues/2524/zenodo-page-shows-only-2015-et-grants

# get Steve Brandt's personal access token for zenodo.org
# create your own personal access token for sandbox.zenodo.org: https://sandbox.zenodo.org/account/settings/applications/tokens/new/

# get data out of current Zenodo entry
export ZENODO_ACCESS=$(secret-tool lookup hostname https://zenodo.org username sbrandt@cct.lsu.edu)
ZENODO_ID=$(python3 ./zenodo.py --list | perl -n -e '/(\d*) The Einstein Toolkit/ && print ($1) && exit 0')
# note down ID of "Einstein Toolkit" (will change each release)
python3 ./zenodo.py --id $ZENODO_ID
mv zupload.py et-zupload.py
wget "https://zenodo.org/record/$ZENODO_ID/files/Definition.md?download=1" -O Definition.md

# recreate in sandbox
export ZENODO_ACCESS=$(secret-tool lookup hostname https://sandbox.zenodo.org username rhaas@illinois.edu)
python3 ./zenodo.py --sandbox --create et-zupload.py
# note down ID of newest (topmost) "Einstein Toolkit"
ZENODO_ID=$(python3 ./zenodo.py --sandbox --list | perl -n -e '/(\d*) The Einstein Toolkit/ && print ($1) && exit 0')
python3 ./zenodo.py --sandbox --id $ZENODO_ID --deposit Definition.md
python3 ./zenodo.py --sandbox --id $ZENODO_ID --publish

# update metadata and dummy deposit file (file must change or Zenodo will reject the new version)
sed -i 's/ET_2020_05/ET_2020_11/g;s/Turing/DeWitt-Morette/g'  Definition.md 
python3 ./zenodo.py --sandbox --id $ZENODO_ID --newversion
ZENODO_ID=$(python3 ./zenodo.py --sandbox --list | perl -n -e '/(\d*) The Einstein Toolkit/ && print ($1) && exit 0')
python3 ./zenodo.py --sandbox --id $ZENODO_ID --deposit Definition.md
python3 ./zenodo.py --sandbox --id $ZENODO_ID --upload
python3 ./zenodo.py --sandbox --id $ZENODO_ID --publish

update version information

update version information in flesh/Makefile in the CCTK_VERSION_XXX variables
update version information in flesh/doc/latex.sty in the \cactustitlepage command

export CCTK_VERSION=Cactus_4.X.0
CCTK_VERSION_MINOR=$(echo $CCTK_VERSION | cut -f2 -d.)
sed -i "s/CCTK_VERSION_MINOR = .*/CCTK_VERSION_MINOR = $CCTK_VERSION_MINOR/" Makefile
sed -i 's/\\cactustitlepage}\[4\]\[4\..*\]/\\cactustitlepage}[4][4.'$CCTK_VERSION_MINOR']/' doc/latex/cactus.sty
git add Makefile doc/latex/cactus.sty
git commit -m 'Cactus: update version in information in Makefile and docs'
make UsersGuide ReferenceManual MaintGuide

update wvuthorns/Baikal/doc/documentation.tex and wvuthorns/BaikalETK/doc/documentation.tex with git hash of nrpytutorial used to generate code. The hash is mentioned in the README file. To compare codes, check out https://github.com/zachetienne/nrpytutorial.git at the hash in question and generate using ./run_Jupyter_notebook.sh Tutorial-BaikalETK.ipynb. In ET_2020_05 this required forcing python3. The generated code lacks using CCTK_REAL for non-vectorized code, and the order in which finite difference orders are checked and included is timing dependent and thus random.

regenerate files

regenerate McLachlan, WeylScal4, CTThorns, and EinsteinExact from their source with the current version of Kranc by running make -j NJOBS in their respective m directory.
check that BaikalVaccum and Baikal can be regenerated using the nrpytutorial hash lised in their README file using python3 BaikalETK/BaikalETK_main_codegen_driver.py
Next run the following script, which
- generates the Cactus configure script by running autoconf2.13 in lib/make
- generates the Cactus loop macros by running perl cctk_Loop.h.pl in src/include
- generates UsersGuide, ReferenceManual and MaintGuide pdf files by running make UsersGuide ReferenceManual MaintGuide

cd lib/make
autoconf2.13
git add configure 
git commit -m 'Cactus: regenerate configure' || true
cd ../../src/include
perl cctk_Loop.h.pl
git commit -m 'Cactus: cctk_Loop.h' || true
cd ../../
make UsersGuide ReferenceManual MaintGuide
cd doc
git add MaintGuide.pdf ReferenceManual.pdf UsersGuide.pdf
git commit -m 'Cactus: regenerate documentation' || true

create branches

Create release branches for all repositories in the ET
- A new ET branch ET_YYYY_MM
- A new ET tag ET_YYYY_MM_v0
- A new Cactus branch Cactus_4.X.0 if in CactusCode
- A new Cactus tag Cactus_4.X.0_v0 if in CactusCode

#!/bin/bash
export ET_RELEASE=ET_XXXX_YY
export CCTK_VERSION=Cactus_4.X.0
set -x -e
for repo in */.git ; do
  cd $repo/..
  pwd
  git checkout master
  git checkout -b $ET_RELEASE
  if [ $(basename $PWD) = manifest ] ; then
    sed -i "/!DEFINE  *COMPONENTLIST_TARGET/a \\\\n!DEFINE ET_RELEASE = $ET_RELEASE" einsteintoolkit.th
    sed -i '/!URL/a \!REPO_BRANCH = ET_RELEASE' einsteintoolkit.th
    sed -i 's!/trunk!/branches/$ET_RELEASE!' einsteintoolkit.th
    git add einsteintoolkit.th
    git commit -m 'einsteintoolkit.th: use release branch'
  fi
  git tag ${ET_RELEASE}_v0
  git push --tags --set-upstream origin $ET_RELEASE
  if git remote get-url origin | grep cactuscode ; then
    git branch $CCTK_VERSION
    git tag ${CCTK_VERSION}_v0
    git push --tags --set-upstream origin $CCTK_VERSION
  fi
  cd - >/dev/null
  sleep 5 # bitbucket enforces some rate limit on pushes its seems
done

Create a release branch in master git repo at https://bitbucket.org/einsteintoolkit/einsteintoolkit via:

export ET_RELEASE=ET_XXXX_YY
git checkout -b $ET_RELEASE
sed -i "s/master/$ET_RELEASE/" .gitmodules
git add .gitmodules
git submodule foreach bash -c "git fetch origin '+refs/heads/*:refs/remotes/origin/*'; git checkout origin/$ET_RELEASE"
git commit -am "Create release branch for $ET_RELEASE"

update branch mentioned in https://build-test.barrywardell.net/job/EinsteinToolkitReleased/configure and trigger a build
create a new version and milestone on https://bitbucket.org/einsteintoolkit/tickets/admin/issues/versions and https://bitbucket.org/einsteintoolkit/tickets/admin/issues/milestones

update websites and online documentation

https://docs.einsteintoolkit.org/et-docs/Editing_the_Einstein_Toolkit_website

Update main ET web site (update version numbers, urls), searching for ET_YYYY_MM finds them all

#!/bin/bash

set -e -x

export ET_RELEASE=ET_2020_05
export PREVIOUS_ET_RELEASE=ET_2019_10

export ET_RELEASE_CODENAME=Turing
export PREVIOUS_ET_RELEASE_CODENAME=Mayer

export ET_RELEASE_URL="https://en.wikipedia.org/wiki/Alan_Turing"
export PREVIOUS_ET_RELEASE_URL="https://en.wikipedia.org/wiki/Maria_Goeppert_Mayer"

export ET_RELEASE_DATE="May 31st, 2020"

ALL_FILES=$(git grep -l "\($PREVIOUS_ET_RELEASE\|$PREVIOUS_ET_RELEASE_CODENAME\)"  | grep -v 'about/releases/' | grep -vF past-releases.html | grep -vF publications/2013_MHD/index.php | grep -vF mp.html) 

# update URL first since it tends to include the release codename
sed -i "s!$PREVIOUS_ET_RELEASE_URL!$ET_RELEASE_URL!g" index.html

# update release names
sed -i "s/$PREVIOUS_ET_RELEASE/$ET_RELEASE/g" $ALL_FILES
sed -i "s/$PREVIOUS_ET_RELEASE_CODENAME/$ET_RELEASE_CODENAME/g" $ALL_FILES

# release date
sed -i "s/[(]released on [^)]*[)]/(released on $ET_RELEASE_DATE)/g" download.html

# update past reelases, mark this one as most recent
$EDITOR past-releases.html

# add news item to front page
$EDITOR index.html

git diff

git add $ALL_FILES past-releases.html download.html index.html
git commit -m "update to $ET_RELEASE"

Update simfactory.org https://svn.cct.lsu.edu/repos/numrel/simfactory2/www/

sed -i "s/$PREVIOUS_ET_RELEASE/$ET_RELEASE/g" simfactory/download/index.php

update CactusTutorial.ipynb in https://github.com:nds-org/jupyter-et.git

sed -i "s/$PREVIOUS_ET_RELEASE/$ET_RELEASE/g" CactusTutorial.ipynb

log into etkhub.ndslabs.org, pull the repo, and rebuild the docker image

To update cactuscode.org: git clone git@github.com:EinsteinToolkit/cactuscode.org.git
- affected by SSL issue in: https://svn.cactuscode.org/www

#/bin/bash

set -e -x

PREVIOUS_ET_RELEASE=ET_2020_05
ET_RELEASE=ET_2020_11

PREVIOUS_CACTUS_VERSION=4.8.0
CACTUS_VERSION=4.9.0

PREVIOUS_ET_WIKIPEDIA="Alan_Turing"
ET_WIKIPEDIA="Cécile_DeWitt-Morette"

PREVIOUS_ET_NAME="Turing"
ET_NAME="DeWitt-Morette"

ET_DATE="$(date +"%B %d, %Y")"
AUTHOR="$(git config --get user.name)"

cd media/news

cp -a $PREVIOUS_ET_RELEASE $ET_RELEASE
sed -i "s!/$PREVIOUS_ET_WIKIPEDIA!/$ET_WIKIPEDIA!g" $ET_RELEASE/index.md
sed -i "s!$PREVIOUS_ET_NAME!$ET_NAME!g" $ET_RELEASE/index.md
sed -i "s!^### .*!### $ET_DATE $AUTHOR!" $ET_RELEASE/index.md

cp -a cactus_$PREVIOUS_CACTUS_VERSION cactus_$CACTUS_VERSION
sed -i "s!${PREVIOUS_CACTUS_VERSION//./[.]}!$CACTUS_VERSION!g;" cactus_$CACTUS_VERSION/index.md
sed -i "s!/$PREVIOUS_ET_WIKIPEDIA!/$ET_WIKIPEDIA!g" cactus_$CACTUS_VERSION/index.md
sed -i "s!$PREVIOUS_ET_NAME!$ET_NAME!g" cactus_$CACTUS_VERSION/index.md
sed -i "s!^### .*!### $ET_DATE $AUTHOR!" cactus_$CACTUS_VERSION/index.md

NEWS="$(<../../_data/news.yml)"
cat >../../_data/news.yml <<EOF
- date: "$ET_DATE"
  link: "$ET_RELEASE/index.html"
  title: 'Einstein Toolkit "$ET_NAME" Release'
- date: "$ET_DATE"
  link: "cactus_$CACTUS_VERSION/index.html"
  title: 'Cactus $CACTUS_VERSION Release'
$NEWS
EOF

To update simfactory.org: 'svn checkout https://svn.cct.lsu.edu/repos/numrel/simfactory2/www' and modify
- need to request write access to repository first
- sed -i 's/ET_2019_10/ET_2020_05/' simfactory/download/index.php
once EinsteinToolkitDoc documentation finishes building on Jenkins, use trigger to trigger an update of ET website. The documentation is build once a day and updates the website, so a manual trigger is optional.
update Cactus Wikipedia entry https://en.wikipedia.org/wiki/Cactus_Framework

release anouncement issues

Ensure email does not go past column 72 to support old email clients.
Send the announcement to the release team and maintainers@einsteintoolkit.org to ensure that the email client and/or server does not scramble the text in any way.
ANNOUNCE: users@einsteintoolkit.org, news@cactuscode.org, users@cactuscode.org
ACCNOUNCE: http://hyperspace.uni-frankfurt.de/
- Keywords used on hyperspace: Einstein Toolkit, numerical relativity, cactus, carpet, software
- In the URL section, put the html link.
- No manual breaks or non-ascii characters.
- Post as a news item.
- must be short enough to be acceptable: compare http://einsteintoolkit.org/about/releases/ET_2020_05_announcement.html and https://hyperspace.uni-frankfurt.de/2020/05/30/the-twentieth-release-of-the-einstein-toolkit/ . The hypersapce editor says that https://hyperspace.uni-frankfurt.de/2020/05/30/the-twentieth-release-of-the-einstein-toolkit/ is now of appropriate length.

On einsteintoolkit.org

ThornGuide.php is in /www/einstein/www/documentation
It draws on the autogenerated http doc files, which are found here:

 /var/www/einstein/documentation

Rebuild the website to update docs using https://github.com/stevenrbrandt/et-websites.git

 docker build --no-cache -f etk-website.docker -t stevenrbrandt/etk-website .
 docker push stevenrbrandt/etk-website

Other stuff

Changes to announce

First grab the latest dev version:

 curl -kLO https://raw.githubusercontent.com/gridaphobe/CRL/master/GetComponents
 chmod a+x GetComponents
 ./GetComponents --parallel https://bitbucket.org/einsteintoolkit/manifest/raw/master/einsteintoolkit.th

Then in that directory, the following script may be helpful in figuring out what has changed since the last release:

 PREVRELEASEMONTH=11
 PREVRELEASEYEAR=2020
 FORMAT="pretty:%h %an: %s"
 ####
 TAG="ET_${PREVRELEASEYEAR}_${PREVRELEASEMONTH}_v0"
 DATE="${PREVRELEASEMONTH}/01/${PREVRELEASEYEAR}"
 for i in repos/*/.git
 do
   export GIT_DIR=$i
   echo "CHANGES FOR $(dirname $i)"
   git fetch --tags 1>/dev/null 2>/dev/null
   git log ${TAG}..master --format="$FORMAT" 2>/dev/null
   E=$?
   if [ $E != 0 ]
   then
     echo " >> TAG ${TAG} missing for repo, using date."
     git log $(git rev-list -n 1 --before="${DATE} 00:00" master)..master --format="$FORMAT"
   fi
 done

Note that when analyzing the output from the *nrpytutorial/* repo, you'll need to be careful to only check for changes to NRPyPN; all other changes are not ET related.

creating release branches (outdated version control systems)

- svn: svn copy https://<repository-server>/<repository-path>/trunk https://<repository-server>/<repository-path>/branches/ET_2011_05
- darcs: clone the repository, appending a suffix to the name
- git: git checkout -b ET_2011_05 ; git push --set-upstream origin ET_2011_05

Release Process

Contents

Release Process

Timeline for a release and estimated time required

Helpful tools and notes

update developers.txt

drafting Zenodo entry

update version information

regenerate files

create branches

update websites and online documentation

release anouncement issues

On einsteintoolkit.org

Other stuff

Changes to announce

creating release branches (outdated version control systems)

Navigation menu

Personal tools

Namespaces

Variants

Views

More

Search

Navigation

Toolbox