Skip to content

Release Procedures

Jump to bottom
Paul Huwe edited this page May 29, 2021 · 23 revisions

Release Procedures

Releases are made on release branches. When done the branch is merged with the stable branch via a Pull Request (PR).

The example below creates a hypothetical release version 0.3.0.

For this setup we assume the release is made in a local directory, other than your romancal working directory, called releases. This workflow assumes working directly with the spacetelescope repository.

Clone the repository on spacetelescope.

 cd releases
 git clone https://github.com/spacetelescope/romancal.git
 # Rename spacetelescope remote to upstream
 git remote rename origin upstream

Clone your fork and set up working branch:

 git remote add <UserName> https://github.com/<UserName>/romancal.git
 git checkout -b ReleaseDocs upstream/main

Prepare the main branch for release

  1. Make last changes to the main branch. Edit CHANGES.rst to set the release date. If necessary make other code changes (there shouldn't really be any changes at this point).

  2. Update README.rst to show the latest release version in the "Software vs DMS build version map" and be sure to update the date and CRDS_CONTEXT for this release. The context can be obtained from Nadia Dencheva or David Kauffman. (Temporarily, it can be obtained from the test server: roman-crds-test.stsci.edu)

  3. Commit changes to your fork:

git add CHANGES.rst README.md 
git commit -m "Release 0.3.0 document updates."
git push <UserName> ReleaseDocs
  1. Create Pull Request from the ReleaseDocs branch on your fork to spacetelescope.

Prepare the release branch

If you're making a major or minor version release, then the release branch will not yet exist. Verify that <UserName> points to your fork and upstream points to the spacetelescope repo. I.e. the following (or ssh equivalents):

>git remote -v
<UserName> https://github.com/<UserName>/romancal.git (fetch)
<UserName> https://github.com/<UserName>/romancal.git (push)
upstream	https://github.com/spacetelescope/romancal.git (fetch)
upstream	https://github.com/spacetelescope/romancal.git (push)
  1. Check that the last commit in the upstream main log is as expected:
git log upstream main
  1. Create the new branch for release, based off of the spacetelescope main 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 0.3.0, name the branch 0.3.x.
git checkout -b 0.3.x upstream/main
  1. Push the 0.3.x branch to spacetelescope. Note: this requires having write permission to the spacetelescope repository. If you don’t have that, please consult Nadia Dencheva or David Davis.
git push upstream 0.3.x
  1. Tag the release branch with the new release and push the tag to the forked repository. Note, make sure GA runs the tests with the public releases of astropy and asdf. 
git tag -a “0.3.0” -m "romancal release 0.3.0”
git push <UserName> 0.3.0

Prepare main for further development

  1. Edit Changes.rst to add a new section at the top of the file for the next release, e.g.
0.3.x (unreleased)
==================
  1. Commit changes to your fork:
git add CHANGES.rst 
git commit -m "Release 0.3.x document updates."
git push <UserName> 0.3.x

  1. Create Pull Request from the 0.3.x branch on your fork to spacetelescope.

  2. Tag the main branch for further development. The suggested tag is a minimal increment of the latest release version tag, followed by a. The tag name should be chosen in such a way that conda would resolve it as the latest tag. Again note: this requires having write permission to the spacetelescope repository. If you don’t have that, please consult Nadia Dencheva or David Davis.

git tag -a “0.3.0a” -m "tagging for further development"
git push upstream 0.3.0a

Publish to test.pypi.org

Before proceeding, you will need to pip install twine.

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

    $ git checkout 0.3.0
$ git clean -xdf

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

    $ twine upload --repository testpypi dist/*

  3. 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 romancal[test]

  4. Run the tests on the installed package. Change to a directory that does not contain the romancal source and confirm that tests pass on the installed package.:

    $ pushd /
$ pytest romancal
$ popd

  5. 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

Pypi Update

  1. Checkout the release tag.
git checkout 0.3.0
  1. Clean the working directory and build the distribution package.
git clean -dfx
python setup.py build sdist

  1. Test the distribution by going into the dist directory , unpacking and running the tests. Make sure the tests are run with the stable versions (publicly released versions) of astropy and asdf. If the tests pass with stable versions, proceed with the release.

  2. Clean after the tests and build the distribution again. Upload the package to PYPI.

git clean -dfx
python setup.py build sdist
twine upload dist/romancal-0.3.0.tar.gz

Check and verify that Pypi has the latest upload. You can look at upload history or at the download area.

Github Update

Go to the main github repository and the release tab and draft a new release with the existing A.B.C tag used above. Use a release title "Roman Build A.B rcN" where N is the current release candidate for DMS, and include the changelog. We can always remove the "rcN" part from the title later if, say, rcN+1 turns out to be the final release.

Update artifactory

TDB

Clone this wiki locally