Release Process

These steps describe how to make a release. This guide assumes that you have cloned roman_datamodels, and added a remote named upstream pointing to the central repository:

git remote add upstream https://github.com/spacetelescope/roman_datamodels.git

1. Update metadata in the main branch

These steps should be undertaken on the main branch:

1. Run towncrier build with the desired release version, to build the next changelog entry in CHANGES.rst from fragments in the changes/ directory:

   pip install towncrier
   towncrier build --version 0.17.0

2. Update pyproject.toml to pin the rad dependency above the newest release that has API-breaking changes (i.e. the newest minor release):

   [project]
   dependencies = [
     "rad >= 0.17.0",
   ]

Caution

PyPI will reject any submission with Git dependencies in its metadata (i.e. git+https://github.com/spacetelescope/rad.git@main). Dependencies must be defined against a released version available on PyPI (i.e. rad>=0.17.0).

3. Commit your changes and push to main on spacetelescope/roman_datamodels.

2. Create or update 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. Select one of the next two sections accordingly.

New major / minor version

1. Fetch and checkout the upstream main:

   git fetch --all --tags
   git checkout -t upstream/main

2. Inspect the log to ensure that no commits have snuck in since your changelog updates:

   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.8.0, name the branch release/1.8.x.

git checkout -b release/a.b.x

4. Push the branch to the upstream remote:

   git push -u upstream HEAD

5. GitHub actions should notice the new branch and run the tests. Wait until the job completes before proceeding.

Patch release of an existing major / minor version

In the case of a patch release, the release branch will already exist.

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

   git checkout release/a.b.x
   git pull

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

   git cherry-pick ...

3. Push updates to the upstream remote:

   git push upstream HEAD

3. Review the release branch's latest automated test run

The creation or update of the release branch should have triggered a CI job on GitHub actions. Find the latest build on the main branch in the Actions tab: https://github.com/spacetelescope/roman_datamodels/actions/workflows/ci.yml?query=branch%3Amain

4. Run tests on downstream packages against the desired release commit

Once the release branch is situated, it's a good idea to confirm that our release candidate doesn't break the following test suites:

• romancal regression tests (add a PEP508 string to the pip dependencies input field that points to the release commit, e.g. git+https://github.com/spacetelescope/roman_datamodels.git@fbd97cc)

5. Tag the desired release commit with the release version

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:

   git tag -a a.b.c -m "a.b.c on release/a.b.x"

2. Push the new tag to the upstream remote:

   git push upstream a.b.c

6. Maintain the stable branch (if necessary)

The stable branch points to the latest official release of roman_datamodels. If the current release has become the latest, then the next step is to rewrite the stable branch to point our new tag.

git checkout stable
git reset --hard a.b.c
git push upstream stable --force

7. Make a GitHub release and publish the package to PyPI

Create a new GitHub release

1. Visit the spacetelescope/roman_datamodels repository's releases page.

2. Click Draft a new release.

3. Select the existing tag that you just created and pushed, and title the release the same as the tag (i.e., a.b.c).

4. Publish the release.

Validate that the package did publish to PyPI

Publishing the GitHub release should trigger an automated workflow that should build the wheel and source distribution and publish the package to PyPI.

After this workflow completes, you can confirm that the new release appears on PyPI: https://pypi.org/project/roman_datamodels/#history

Additionally, you can test installing the new version with pip:

pip install roman_datamodels==a.b.c

6. Prepare main / master for further development

1. Make sure CHANGES.rst has a section for the next release.

2. Tag main / master for further development (if necessary)

   If the release branch has diverged from main / master, you will need to tag the HEAD of main / master with a development tag. This allows the setuptools-scm plugin to show the correct version for a locally installation. For example, if we just released version 1.2.1, the development tag would be 1.2.2.dev.

   git fetch upstream
   git checkout upstream/master
   git tag -a a.b.d.dev -m "development tag after divergence"
   git push upstream a.b.d.dev