Skip to content

Latest commit

 

History

History
191 lines (139 loc) · 4.78 KB

RELEASE.md

File metadata and controls

191 lines (139 loc) · 4.78 KB
Raw

Publishing a release

This page describes the steps required to author a release of the gwosc Python client.

Notes:

  • gwosc uses the stable mainline branching model for releases.

  • All release numbers must follow Semantic Versioning 2 and include major, minor, and patch numbers, e.g. 1.0.0 rather than 1.0 or just 1.

  • The instructions below presume that you have cloned the gwosc/client gitlab project with https://git.ligo.org/gwosc/client.git configured as a remote named upstream:

    git remote add upstream https://git.ligo.org/gwosc/client.git

Step-by-step

Release notes

All releases should be accompanied by a comprehensive set of release notes, written using GitLab Flavoured Markdown (GLFM) syntax. This normally takes the form of minimum summary information, then an itemised list of changes included in this release relative to the previous release, grouped by their API-compatibility:

  • Backwards-incompatible changes,
  • Backwards-compatible changes,
  • Bug fixes and other changes.

The list of changes can just be a list of the merge requests associated with the relevant gitlab milestone, including the !123 reference and a small summary, e.g.:

  • [!123] fix bug in gwosc.timeline.get_segments

Include a link to the release itself at the bottom of the release notes.

Full example:

gwosc 3.0.0

New major release of the GWOSC Python client. This is the first release to formally support Python 4.0.0.

Backwards-incompatible changes:

  • [!300] remove deprecated thing
  • [!301] drop support for Python 3.10

Backwards-compatible changes:

  • [!302] add gwosc.magic.thing() function to do magic

Bug fixes and other changes:

  • [!303] fix bug in gwosc.timeline.get_segments
  • [!304] fix typo in docstring for gwosc.datasets.find_datasets

For a full list of changes related to this release, please see

https://git.ligo.org/gwosc/client/-/releases/v3.0.0

Major/minor release

For a major (X.0.0) or minor (X.Y.0) release:

  1. Fetch the latest commits for the upstream/main branch:

    git fetch upstream
git checkout upstream/main

  2. Choose the X.Y version number:

    export GWOSC_VERSION="X.Y"

    e.g.

    export GWOSC_VERSION="1.2"

  3. Tag the release:

    git tag --sign v${GWOSC_VERSION}.0

    This will open an editor, into which you should insert the release notes.

  4. Create a maintenance branch:

    git branch release/${GWOSC_VERSION}.x

  5. Publish the new tag and the maintenance branch:

    git push --signed=if-asked upstream v${GWOSC_VERSION}.0 release/${GWOSC_VERSION}.x

Bug-fix release

Bug-fix (patch) releases are handled slightly differently, mainly due to the use of a release/X.Y.x maintenance branch.

  1. Choose the X.Y.Z version number:

    export GWOSC_VERSION="X.Y.Z"

    e.g.

    export GWOSC_VERSION="1.2.3"

  2. Fetch the latest commits for the release/X.Y.x maintenance branch:

    git fetch upstream
git checkout upstream/release/${GWOSC_VERSION%.*}.x

  3. Tag the release:

    git tag --sign v${GWOSC_VERSION}

    This will open an editor, into which you should insert the release notes.

  4. Publish the new tag:

    git push --signed=if-asked upstream v${GWOSC_VERSION}

  5. Draft a release on GitLab

Distributing the new release package

Package distributions for PyPI, Conda, Debian, and RHEL are done manually:

PyPI

To create a new release on PyPI:

# remove old distributions
git clean -dfX
# check out the release tag
git checkout vX.Y.Z
# generate the distributions
python -m build
# upload the distributions to pypi.org
python -m twine upload --sign dist/gwosc-X.Y.Z*

Conda

Once the PyPI upload has completed, the conda-forge bot will automatically open a pull request to conda-forge/gwosc-feedstock. Just double-check that the dependencies and tests are up-to-date, then merge.

Debian/RHEL

To requests Debian/RHEL packages to be built and for this new version to be included in the IGWN software repositories, open an SCCB request.