Release procedures

We assume you have a local clone of your fork of https://github.com/spacetelescope/drizzle and that origin points to your fork and upstream points the central repo. I.e. the following (or ssh equivalents):

$ git remote -v
origin	https://github.com/jdavies-st/drizzle.git (fetch)
origin	https://github.com/jdavies-st/drizzle.git (push)
upstream	https://github.com/spacetelescope/drizzle.git (fetch)
upstream	https://github.com/spacetelescope/drizzle.git (push)

Prepare master branch for release

These steps should be undertaken on the master branch:

1. Update CHANGES.rst to have the correct release version and date. Change "unreleased" next to the intended release to the current date in YYYY-MM-DD format.

2. Create a PR against upstream/master and merge it.

Prepare the release branch

If you're making a major or minor version release, then the release branch will not yet exist. If you're releasing a patch version, then a release branch will already exist and patch may include everything on master or need cherry-picking. Following one of the next 3 options accordingly. The following steps assume that the spacetelescope/drizzle remote is named upstream, just as above.

Option 1: Major or minor version release

1. Update pointer to master:

   $ git fetch upstream
   $ git checkout upstream/master
   

2. Verify that the last commit in the log is as expected:

   $ git log
   

3. Create a new release branch. The name of the release branch should share the major and minor version of your release version, but the patch version should be x. For example, when releasing 1.2.0, name the branch 1.2.x.

   $ git checkout -b a.b.x upstream/master
   

4. Push the branch to the upstream remote.

   $ git push -u upstream HEAD
   

Github actions CI should notice the updated branch and run the tests which you can check here. Wait until the build passes before proceeding.

Option 2: Patch release (including all of master)

If your patch release will include everything on master, the procedure is very similar to a major/minor release, but the release branch will already exist. So if you need to deliver a 1.2.1 patch to 1.2.0, then you will do your work in branch 1.2.x.

1. Checkout and freshen release branch (this assumes that your local branch is already tracking upstream/a.b.x):

   $ git checkout a.b.x
   $ git pull
   

2. Pull all changes on master into the release branch:

   $ git fetch upstream
   $ git pull upstream master
   

3. Push updates to the upstream remote:

   $ git push upstream HEAD
   

Github actions CI should notice the updated branch and run the tests which you can check here. Wait until the build passes before proceeding.

Option 3: Patch release (requiring cherry-picking from master)

In the case of a patch release, the release branch will already exist. So if you need to deliver a 1.2.1 patch to 1.2.0, then you will do your work in branch 1.2.x.

1. Checkout and freshen release branch (this assumes that your local branch is already tracking upstream/a.b.x):

   $ git checkout a.b.x
   $ git pull
   

2. Cherry-pick relevant commits from master that should be included in the patch release (including the new changelog commit):

   $ git cherry-pick ...
   

3. Push updates to the upstream remote:

   $ git push upstream HEAD
   

Github actions CI should notice the updated branch and run the tests which you can check here. Wait until the build passes before proceeding.

Create the release tag locally

At this point, you should have the release branch checked out and ready to tag.

1. Create an annotated tag with a name that matches your intended release and a useful message.

   $ git tag -a a.b.c -m "Tagging a.b.c on release branch a.b.x"
   

Publish to test.pypi.org

This step is optional, but it is a good sanity check, especially if there's been any changes to the install procedure (i.e. setup.py, setup.cfg, pyproject.toml) since the last release, or if there's been any changes to the README or anything else that gets included in long_description in setup.cfg.

This step requires permissions to write to test.pypi.org for drizzle.

Before proceeding, you will need to pip install twine build.

1. Checkout the release tag, clean the directory, and make sure umask and permissions are set correctly:

   $ git checkout a.b.c
   $ git clean -xdf
   $ umask 0022
   $ chmod -R a+Xr .
   

2. Check the package setup and create the package sdist and wheel:

   $ python -m build .
   

3. Upload the package to PyPi's test server (you need an account and be added as maintainer):

   $ twine check --strict dist/*
   $ twine upload --repository testpypi dist/*
   

4. Check that it looks good on the test server. Make sure it installs without errors in a new virtual env:

   $ pip install -i https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple drizzle[test]==a.b.c
   

5. Run the tests on the installed package. Change to a directory that does not contain the drizzle source and confirm that tests pass on the installed package.

   $ pushd /
   $ pytest --pyargs drizzle
   $ popd
   

6. If the package looks good on test.pypi.org and installs OK and the tests pass, then proceed.

Make the release official on Github and Pypi

1. If publishing to the PyPi test server above worked well, push the new tag to the upstream remote on Github:

   $ git push upstream a.b.c
   

2. Go to https://github.com/spacetelescope/drizzle/releases and draft a new release with the existing a.b.c tag used above. When saved, this will kick off the Github action to deliver the package to Pypi officially.

3. Check that it was delivered to Pypi (https://pypi.org/project/drizzle/).

Prepare master for further development

Create and merge a PR to master updating CHANGES.rst, opening it up for new features and bugfixes. The diff should look something like this

$ git diff
diff --git a/CHANGES.rst b/CHANGES.rst
index e8771c7b..d7fac87e 100644
--- a/CHANGES.rst
+++ b/CHANGES.rst
@@ -1,3 +1,8 @@
+0.16.1 (unreleased)
+===================
+
+
+
0.16.0 (2020-05-04)
===================

Tag master for further development (if necessary)

This only really needs to be done if we've done a patch release on a release branch that has cherry-picked commits on it, making it diverge from master. Because of the divergence, we'll need to tag the HEAD of master with a development tag. This allows the setuptools-scm plugin to identify code installed from master as the latest version. So if we just released version 1.2.1, then the development tag will be 1.2.2.dev.

$ git fetch upstream
$ git checkout upstream/master
$ git tag -a a.b.d.dev -m "Tagging a.b.d.dev"
$ git push upstream a.b.d.dev