Home

Notes on cutting a release

1. Create a release branch (on GitHub) for each new major or minor release, i.e. 3.1_rel onto which all the 3.1.x releases will live.

2. Clone repo and checkout release branch, on that release branch in your local clone:

   1. In setup.py change default_version to be the tag of the release you are creating. i.e. 3.1.0
   2. Similarly in docs/source/conf.py change version and release to the same tag.
   3. Commit and push these changes to github (on the release branch)

3. On github create the new release (on the release branch). This will create the 3.1.0 tag.

4. Attach as an asset for this new release, the examples subdir as it's own .zip file:

   zip -r ccsi-foqus-3.8.0-examples.zip examples
   

5. git pull in your local repo to bring down the new release tag and check out the release branch i.e. git co 3.1_rel.

   At this point (on the release branch) a git describe --tags --dirty should show the release tag (3.1.0) and nothing else (not 3.1.0rc0-dirty, etc.)

6. Create the pypi package

   Note that pypi will not allow you to replace a package with the same version number (even if you delete the old one). So keep that in mind before uploading a package to either the main or test site.

   1. Start from a clean conda env:

      conda remove --name ccsi-foqus --all -y       # remove any old conda env
      conda create --name ccsi-foqus python=3.9 -y  # create an entirely new conda env
      conda activate ccsi-foqus
      

   2. In a clean repo on the release tag, get set up to build package:

      git clone git@github.com:CCSI-Toolset/FOQUS.git
      cd FOQUS
      git co 3.1.0
      git clean -dfx   # If using an existing repo
      pip install --upgrade setuptools wheel twine pip
      

   3. Build and push to test pypi

      pip install --no-cache-dir .  # Not setup.py or -e or -r requirements.txt
      python setup.py sdist bdist_wheel
      # check the size of the directory, PyPI upload with fail if it's > 100 MB
      ls -lh dist/*
      _maxsize=100000  # 100 MB
      _dirsize=$(du -sk dist/ | cut -f 1) ; echo $_dirsize
      [ "$_dirsize" -lt "$_maxsize" ] || echo "too big!"
      # if larger, you can delete examples and re-create sdist/bdist_wheel
      # Check for any old builds in ./dist/
      twine upload --repository-url https://test.pypi.org/legacy/ dist/*  # Upload to test pypi
      

   4. Test package from test PyPi In a new conda env, in an empty dir:

      pip install -i https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple ccsi-foqus
      foqus  # Start app
      

      NOTE: to install Release Candidate versions (e.g. 3.7.0rc0) with pip, the full PyPI package version must be specified using the == operator, e.g. ccsi-foqus==3.7.0rc0

      Capture the specific versions installed at this point in time:

      pip freeze > requirements_3.14.0rc0.txt
      

      Then upload that requirements_<rel>.txt file as an asset in the GitHub page for this release.

   5. Push to real PyPi

      twine upload dist/*
      

7. git co master and change setup.py and docs/sources/conf.py in the same places as above, but now on master change to the next "dev" version, i.e. 3.1.0dev to 3.2.0dev. Stage, check-in these changes and then tag them with a new "dev" tag: i.e. git tag 3.2.0dev, then push up to github (git push --tags or the tag won't get pushed up.)

   At this point (on master) a git describe --tags --dirty should show the dev tag (3.2.0dev) and nothing else (not 3.2.0dev-dirty, etc.)

8. Update ReadTheDocs so that it builds from the new tag and uses that as the default version to display.

9. Announce the release:

   1. Via an email to the leadership, iab and users lists

   2. A news item on the https://www.acceleratecarboncapture.org site.