How to Prepare a Release

In this guide, we’ll cover:

  • Preparing The Code For Release

  • Creating A Release On GitHub

  • Updating The sha256

  • Releasing The Software On Anaconda

  • Creating a New Version of the Documentation

Preparing The Code For Release

1. Pull the lastest code from whatever branch you want to release from. It’s usually master. We will assume this to be the case for all instructions on this page.

git checkout master
git pull origin master

Or checkout a branch:

git fetch origin master
git checkout -b <branch-name> origin/master

  1. Edit version in setup.py to the new version. Don’t prefix this with a “v”.

  2. Edit __version__ in zstash/__init__.py. Prefix this with a “v”.

4. Change the version in conda/meta.yaml. version is what the version of the software will be on Anaconda. Don’t prefix this with a “v”. Reset the build number to 0 if necessary (i.e., if higher builds of the previous version have been made).

  1. Commit and push your changes.

    git commit -am 'Update to v0.4.1'
git push origin master

Or:

git commit -am 'Update to v0.4.1'
git push <fork-name> <branch-name>
# Create pull request for the master branch

Creating A Release On GitHub

1. Go to the Releases on the GitHub repo of the project here. and draft a new release.

2. Tag version and Release title should both be the version, including the “v”. Target should be master. Use Describe this release to write what features the release adds. You can scroll through Zstash commits to see what features have been added recently.

  1. Click “Publish release”.

Updating The sha256

  1. Download “Source code (.tar.gz)” from the GitHub releases page.

  2. Run shasum -a 256 on this file. For example:

    shasum -a 256 zstash-0.4.1.tar.gz

3. On your machine, pull the latest version of the code. This will have the conda/meta.yaml we edited in the first section.

git checkout master
git pull origin master
Or:
git fetch origin master
git checkout -b <branch-name> origin/master

  1. Change sha256 in conda/meta.yaml to the result of step 2.

  2. Commit and push your changes.

    git commit -am 'Edit sha256 for v0.4.1'
git push origin master

Or:

git commit -am 'Edit sha256 for v0.4.1'
git push <fork-name> <branch-name>
# Create pull request for the master branch

Releasing The Software On Anaconda

Since we’re building with noarch, you can run the below steps on either a Linux or macOS machine. You do not need to run these steps on both.

It is recommended to use Miniconda3 rather than Anacdona3 to build packages. The packages from the base Anaconda3 environment will come from the defaults channel, not the conda-forge channel, and package updates fail when we try to update to the conda-forge version of conda-build. If you don’t have Miniconda3 yet, you can install it from Miniconda3.

  1. Activate the base conda environment if you have not already done so:

    conda activate base

2. Make sure you have the latest versions of conda, conda-build, and anaconda-client by running conda update -n base conda conda-build anaconda-client.

3. On your machine, pull the latest version of the code. This will have the conda/meta.yaml we edited in the first and third sections.

git checkout master
git pull origin master
Or:
git fetch origin master
git checkout -b <branch-name> origin/master

4. Run conda env list. Determine the path for the miniconda3 installation you are using to build the package. Typically, this will be ~/miniconda3. Run rm -rf <path>/conda-bld to ensure that previously built packages are not included in the current build.

5. Run the following commands to make sure the conda-forge channel is included by default and that packages come from that channel whenever possible:

conda config --add channels conda-forge
conda config --set channel_priority strict

6. Run conda build conda/. The conda/ folder is where meta.yaml is located. Keep the output of this command. We’ll use it in step 8.

7. Run conda search --info --use-local zstash. The only dependency should be python >=3.6. In particular, python_abi should not be listed as a dependency.

8. In the output of step 6, you should see something like the below. We only have one package of type noarch, meaning it works on both Linux and OSX and is compatible with multiple versions of Python (3.6, 3.7, 3.8, etc.). Since we have constrained python versions to >= 3.6 in the dependencies, it will not work with Python 2 or any other version of Python <= 3.5.

# Automatic uploading is disabled
# If you want to upload package(s) to anaconda.org later, type:

anaconda upload /usr/local/anaconda3/conda-bld/noarch/zstash-0.4.1-py_0.tar.bz2

# To have conda build upload to anaconda.org automatically, use
# $ conda config --set anaconda_upload yes

Copy the anaconda upload command and append -u e3sm to upload the package to the e3sm Anaconda channel. Below is an example:

anaconda upload /usr/local/anaconda3/conda-bld/noarch/zstash-0.4.1-py_0.tar.bz2 -u e3sm
# If you don't appear to have anaconda installed, try the following:
which conda
# Append the top-level directory for anaconda (e.g., `/usr/local/anaconda3`) to the command.
# For example:
/usr/local/anaconda3/bin/anaconda upload /usr/local/anaconda3/conda-bld/noarch/zstash-0.4.1-py_0.tar.bz2  -u e3sm

If you’re having permission issues uploading a package to the e3sm channel, contact either Jill Zhang (zhang40@llnl.gov) or Rob Jacob (jacob@anl.gov) for permission. You will need to have a Conda account. Then, you can be given permission to upload a package.

  1. Check the https://anaconda.org/e3sm/zstash page to view the newly updated package.

10. Notify the maintainers of the E3SM Unified environment about the new zstash release on the E3SM Confluence site. Be sure to only update the zstash version number in the correct version(s) of the E3SM Unified environment. This is almost certainly one of the versions listed under “Next versions”. If you are uncertain of which to update, leave a comment on the page asking.

Creating a New Version of the Documentation

The main documentation page includes the most up-to-date information. This means it may contain information on features not included in a previous release. The main documentation page, Zstash documentation, does link to the documentation for previous releases.

After you have released a new version of zstash, create a new version of the documentation with the following steps:

# cd into zstash directory
git fetch origin gh-pages
git checkout -b <branch-name> origin/gh-pages
conda activate sphinx
make html
# Copy the latest docs. They now won't be updated regularly.
cp -r docs/html docs/html-v0-4-2 # Replace v0-4-2 with the new version number.
# Copy the latest source. This will be useful if previous versions of the docs have to be updated to fix mistakes.
cp -r source source-v0-4-2 # Replace v0-4-2 with the version number.

Then, edit source/index.rst, adding the link to the new version of the docs to the list of previous versions. This will be of the following form:

`v0.4.2 <https://e3sm-project.github.io/zstash/docs/html-v0-4-2/index.html>`_

Just replace v0.4.2 and v0-4-2 with the new version number.

Then, run make html again to update the new working version of the documentation.

Then, commit and push your changes.

git commit -am 'Link latest documentation version'
git push origin gh-pages

Or:

git commit -am 'Link latest documentation version'
git push <fork-name> <branch-name>
# Create pull request for the gh-pages branch