Skip to content

Software Releases

Jump to bottom
Bryan Hilbert edited this page Oct 13, 2023 · 19 revisions

The jwql team performs a software "release" at the end of each sprint. In this context, the term "release" means the following:

  1. Creating a new branch for changes related to the version release procedure
  2. Updating the version number in setup.py
  3. Updating the CHANGES.rst file
  4. Opening/reviewing/merging pull requests with the release procedure changes
  5. Creating of a new tag/release on GitHub
  6. Upload the newly created release to pypi
  7. Run database_interface.py

Detailed instructions for performing a release are given below.

1. Create a new branch for the release updates

Make sure that the local version of the develop branch is up-to-date. A new branch with the naming convention vx.y.z should be opened off of the develop branch, where x.y.z is the version number of the release (e.g. v0.16.1). This branch should be used for the changes described in the rest of this document.

2. Update the version number in setup.py

The VERSION variable in setup.py should be updated to the new version number, using the x.y.z convention.

3. Update the CHANGES.rst file

In CHANGES.rst, write a concise but detailed description of all of the notable changes that have occurred since the last release. One way to acquire this information is to scroll through the commit history of the project on GitHub, and look for commits in which a pull request was merged. Another way is to sort on the Pull Request page, using something like is:pr is:closed merged:2020-12-31..2021-03-30 base:develop sort:updated-desc

4. Open/review/merge pull requests with the release procedure changes

Once you've committed the changes from (2) and (3) in your branch, push your branch to GitHub using the upstream remote, open two pull requests: one that points to main with the title "Release [main]", and one that points to develop with the title "Release [develop]. Assign reviewers. Either you or the reviewer should eventually merge these pull requests.

5. Create a new tag/release on GitHub

Once the pull request into main from (4) has been merged, click on the releases button on the main page of the jwql repository, then hit the Draft a new release button. The Tag version should be the version number of the release, the Target should be main, the Release title should (also) be the version number of the release, and the Description should match that of the changelog entry in (3). Once all of that information is added, hit the big green Publish release button.

6. Upload the newly created tag/release to PyPI

Once the new tag/release has been created, pull in the changes from upstream (use git fetch upstream so that the tags directory will get the tag for the just-published release) and make a local copy of the tag with git checkout tags/<tag> -b <branchname> (e.g. git checkout tags/1.0.0 -b 1.0.0). So:

    git fetch upstream
    git rebase upstream/main`
    git checkout tags/<tag> -b <branchname>`

While on this branch, create a distribution and upload it to the JWQL PyPI project (note that you will have to be an owner of the PyPI project to do this):

python setup.py sdist bdist_wheel
twine upload -u '<pypi_username>' -p '<pypi_password>' --repository-url https://upload.pypi.org/legacy/ --skip-existing dist/*

7. Run database_interface.py

This needs to be done on each server and for each generic user account. That way if anyone has added new database tables in a recent PR, those tables will be added to all copies of the databases.

Clone this wiki locally