Skip to content
This repository has been archived by the owner on Jul 22, 2021. It is now read-only.

Release Procedure

Jump to bottom
Craig Jones edited this page Sep 19, 2018 · 2 revisions

This page outlines basic procedures for creating a new mosviz release.

Releasing a new major or minor version

For the purposes of this tutorial, we will assume that we are releasing version 1.0.0. We will also assume that there already exists a stable branch that represents the most recently released version prior to this one (e.g. 0.2.1, or something like that). These instructions apply to both major and minor version releases.

Preparing the release branches

  1. From tip of master, create a new branch for the 1.0 release series:

$ git checkout -b v1.0.x master

If we were packaging a minor version release, say 1.2 for example, we would create a v1.2.x branch instead.

  1. Tag the release candidate:

$ git tag -s v1.0.0rc -m "Tagging v1.0.0 release candidate"

  1. Push the new v1.0.x branch to spacetelescope/mosviz and also the v1.0.0rc tag (this step will depend on the way your remotes are named):

$ git push stsci v1.0.x v1.0.0rc

  1. Create a PR from v1.0.x into stable. Wait for CI to complete Do NOT delete the v1.0.x branch once the PR is merged. It will be useful later.

  2. Once CI passes, merge the PR and update your local version of the stable branch:

$ git remote update
$ git checkout stable
$ git pull
  1. Update the version in setup.cfg to reflect the release version of 1.0.0, and commit the change:

$ git commit -a -m "Update version to 1.0.0 in setup.cfg"

  1. Update the release date corresponding to version 1.0.0 in the change log, and commit the change:

$ git commit -a -m "Update change log to reflect v1.0.0 release"

Creating the package

  1. Create a clean environment for preparing the release. We do this to make sure that our build script does not have any dependencies that we are not aware of:
$ conda create -n mosviz-release-1.0.0 python=3.6
$ source activate mosviz-release-1.0.0
  1. Make sure that twine is installed in your environment:

$ pip install twine

  1. Clean the source tree of all existing build artifacts. The easiest way to do this is using git clean -dfx, but you will need to BE CAREFUL. This command will remove all uncommitted files from your working tree, so make sure to move anything that you want to keep (or commit it to another branch):

$ git clean -dfx

  1. From the top level of the source tree, use setuptools to build a source distribution:

$ python ./setup.py build sdist

Testing the package

There should now be a new directory in your source tree called dist that contains a package called mosviz-1.0.0.tar.gz.

  1. Create a clean environment for testing the package (it's probably safe to use the same environment we created for building the package, but you can create a new environment out of an abundance of caution):
$ conda create -n mosviz-release-test python=3.6
$ source activate mosviz-release-test
  1. Use pip to install the package that you just created:

$ pip install /path/to/mosviz/dist/mosviz-1.0.0.tar.gz

If installing the package fails, you will need to fix the problems and rebuild the package. See this section for more information.

  1. If the package installs successfully, then run mosviz and perform any tests that will increase confidence in the release. If any bugs are discovered at this point, see this section for more information. IMPORTANT: When performing this step, do NOT run mosviz from the source directory. Instead, move to some other directory far away from your mosviz source tree. We want to make sure that the package was properly installed in your environment, and that you are testing the installed version.

Releasing the package

Now that the package has been tested, and any bugs have been resolved, it is time to release the package.

  1. Tag the commit on stable corresponding to the actual release:

$ git tag -s v1.0.0 -m "Tagging v1.0.0 release"

  1. Create a pgp signature for the package:

$ gpg --detach-sign -a dist/mosviz-1.0.0.tar.gz

This will create a pgp signature file at dist/mosviz-1.0.0.tar.gz.asc.

  1. Upload the package and signature to PyPi using twine:

$ twine upload dist/mosviz-1.0.0.tar.gz*

You will be prompted for a PyPi username and password, so you will need to have an account before executing this step. If you already have an account, you will need be added as either an owner or maintainer to the mosviz package. NOTE: If you intend to upload the pgp signature, it must be done during the same twine upload as the package itself. It is NOT possible to add a pgp signature to a package that has already been published to PyPi.

Final steps

Hooray, your package is published! That wasn't too terrifying, right? Now there are just a few things to do to get your source repository in working order for the next release.

  1. Publish the tag you created for the 1.0.0 release:

$ git push stsci v1.0.0

  1. Bump the version in setup.py to an unreleased version (1.0.1dev` in the case of this example) and commit.

  2. Add a section to the change log for the unreleased version and commit.

  3. Push these changes to stsci/stable (remote name may vary depending on local setup).

  4. Since the last two commits were on stable, git cherry-pick these commits back onto master, and push them to stsci/master (again, remote name may vary).

  5. Tell all your friends!

Addressing bugs while packaging

Sometimes while installing the new package, or testing the installed package, bugs are discovered. These will need to be addressed before the package is released. Sometimes the bugs can be fixed with a simple change, which can be committed and pushed directly to the stable branch. Keep in mind that any such changes will eventually need to be cherry-picked back onto master as well. It may be useful to submit more complicated changes as a PR to the stable branch, which will allow CI to run.

Once the changes are incorporated, the procedure should be restarted beginning with the steps under Creating the package.

Preparing a bugfix release

Oh no, someone found a bug in your released package! How could that even be possible?!?

This means that you're going to need to issue a bugfix release for the current version. For this example we'll assume that the last released version was 1.0.0. This means that our bugfix release version will be 1.0.1. The steps for creating a bugfix release are largely the same as those for creating a major or minor version release. The main difference is that the release will be based on an existing release branch, rather than a new branch.

It is likely that bugs will reported after new features have already been added to master. For example, you might have already introduced several changes to master that are intended for release in version 1.1.0 or 2.0.0 before you become aware of a bug in 1.0.0. When you prepare the bugfix release, you do NOT want to introduce features that are intended for a future release. The best way to manage this is by backporting relevant bug fixes directly to an existing release branch. The following scenario will illustrate:

  1. A bug is reported by a user of the released 1.0.0 package.
  2. You create a branch that fixes the bug and you open a PR against master. This fixes the bug for all future releases.
  3. You also need to fix the bug for version 1.0.1. In this author's humble opinion, the best way to do this is to follow these steps:
    1. Create a separate branch based on the current release branch: $ git checkout -b bugfix-backport v1.0.x
    2. Cherry-pick the commits that fix the bug onto the new branch. Some careful conflict resolution may be required.
    3. Open a PR merging the backport branch into v1.0.x

If you follow these steps every time that you fix a bug that affects a released version, then creating a bugfix release will be easy. You simply need to tag the release candidate on v1.0.x, then create a PR from v1.0.x to stable. The rest of the steps, starting at #5 under Preparing the release branches should be the same. Just make sure to update the version and change log accordingly.

Releasing for conda

Once the package has been released to PyPi, it is time to update the relevant conda recipes. At the very least this will include astroconda, but it may also include conda-forge.

Preliminaries

[Moved to the bottom as these should already be done]

Several thing should be in place before you begin the release procedure:

  1. Create a PyPi account at https://pypi.org/account/register/. Someone will need to add you as either an owner or maintainer of the mosviz project.

  2. Create a PGP key pair if you don't have one already. The instructions provided by Astropy are quite detailed and useful. It is considered good practice to sign both the releases themselves and the tags associated with releases. In order for the tags to be verified by GitHub, you should register your public pgp key here: https://github.com/settings/keys.

Clone this wiki locally