st-uhubm release instructions
==============================

Overview
--------

Releases are published automatically by:

.github/workflows/release.yml

Pushing a Git tag beginning with "v" starts the GitHub Actions workflow. The
workflow:

1. Checks out the tagged source.
2. Sets up Python.
3. Builds the source distribution and wheel.
4. Stores the distributions as a GitHub Actions artifact.
5. Publishes the distributions to PyPI through Trusted Publishing.

No PyPI API token is required.

In this document:

- X.Y.Z is the Python package version, for example 1.2.3.
- vX.Y.Z is the corresponding Git tag, for example v1.2.3.


One-time setup
--------------

1. Create the "st-uhubm" project on PyPI, or configure a pending trusted
   publisher if the first release has not yet been published.

2. In the PyPI publishing settings, add a trusted publisher with:

   Owner:
       anderlee-nordic

   Repository:
       st-uhubm

   Workflow:
       release.yml

   Environment:
       pypi

3. In the GitHub repository, open:

   Settings -> Environments

4. Create an environment named:

   pypi

5. Optionally add required reviewers to the "pypi" environment. If required
   reviewers are enabled, the publish job waits for approval.

6. Confirm that the publish job in .github/workflows/release.yml has:

   permissions:
     id-token: write


Prepare a release
-----------------

1. Choose the new version number:

   X.Y.Z

2. Set the package version in pyproject.toml:

   version = "X.Y.Z"

   Do not include the "v" prefix in the Python package version.

3. Confirm that src/st_uhubm/__init__.py reads the version from installed
   package metadata. Do not add another hard-coded version.

4. Install the project and release tools:

   python3 -m pip install --upgrade \
       build \
       twine \
       ".[gui,docs]"

5. Run the tests:

   python3 -m pytest

6. Build the documentation and treat warnings as errors:

   rm -rf docs/_build

   python3 -m sphinx \
       -W \
       --keep-going \
       -b html \
       docs \
       docs/_build/html

7. Build the package:

   rm -rf build dist
   python3 -m build

8. Check the generated distributions:

   python3 -m twine check dist/*

9. Confirm that the wheel and source distribution exist:

   ls -l dist/

   The files should include names similar to:

   dist/st_uhubm-X.Y.Z-py3-none-any.whl
   dist/st_uhubm-X.Y.Z.tar.gz

10. Install the generated wheel:

    python3 -m pip install \
        --force-reinstall \
        --no-deps \
        dist/st_uhubm-X.Y.Z-py3-none-any.whl

11. Verify the installed version:

    stuhubm --version

    Expected output:

    stuhubm, version X.Y.Z


Commit and push
---------------

1. Review the changes:

   git status
   git diff

2. Commit the release changes:

   git add pyproject.toml docs README.md src
   git commit -m "Release version X.Y.Z"

3. Push the commit:

   git push origin main

4. Wait for the normal branch checks to pass before creating the release tag.


Create and push the tag
-----------------------

1. Create an annotated Git tag:

   git tag -a vX.Y.Z -m "st-uhubm X.Y.Z"

2. Verify that the tag points to the correct commit:

   git show vX.Y.Z

3. Push the release tag:

   git push origin vX.Y.Z

The package version is X.Y.Z. The corresponding Git tag is vX.Y.Z.


Monitor GitHub Actions
----------------------

1. Open the repository:

   https://github.com/anderlee-nordic/st-uhubm

2. Open the Actions tab.

3. Select the "Publish to PyPI" workflow run for tag vX.Y.Z.

4. Confirm that the "build" job succeeds.

5. If the "pypi" environment requires approval, review and approve the
   "publish" job.

6. Confirm that the "publish" job succeeds.

Do not upload the same distributions manually after the GitHub Actions publish
job succeeds.


Create the GitHub release
-------------------------

1. Open:

   https://github.com/anderlee-nordic/st-uhubm/releases/new

2. Select the existing tag:

   vX.Y.Z

3. Set the release title:

   st-uhubm X.Y.Z

4. Add release notes describing the main changes.

5. Optionally use GitHub's generated release notes.

6. Publish the release.

The tag push starts the current PyPI workflow. Publishing the GitHub release
page does not start it.


Verify PyPI
-----------

1. Open:

   https://pypi.org/project/st-uhubm/

2. Confirm that version X.Y.Z is listed.

3. Create a clean virtual environment:

   python3 -m venv /tmp/st-uhubm-release-check
   source /tmp/st-uhubm-release-check/bin/activate

4. Install the package from PyPI:

   python3 -m pip install --upgrade pip
   python3 -m pip install st-uhubm

5. Verify the installed version:

   stuhubm --version

   Expected output:

   stuhubm, version X.Y.Z

6. Test the optional GUI installation if needed:

   python3 -m pip install "st-uhubm[gui]"
   stuhubm-gui


Verify documentation
--------------------

Read the Docs should rebuild after the source push if its webhook is enabled.

Open:

https://st-uhubm.readthedocs.io/

Confirm that the latest documentation contains the release changes.

If versioned documentation is enabled, activate the vX.Y.Z version in the
Read the Docs project dashboard.


If the workflow fails before publishing
---------------------------------------

If the workflow fails before the version is uploaded to PyPI:

1. Fix the problem.

2. Commit and push the fix:

   git add .
   git commit -m "Fix release X.Y.Z"
   git push origin main

3. Delete the old remote tag:

   git push origin --delete vX.Y.Z

4. Delete the old local tag:

   git tag -d vX.Y.Z

5. Recreate the tag on the corrected commit:

   git tag -a vX.Y.Z -m "st-uhubm X.Y.Z"

6. Push the corrected tag:

   git push origin vX.Y.Z


If the version was already published
------------------------------------

PyPI does not allow an existing distribution version to be replaced.

If X.Y.Z was already published:

1. Do not delete and recreate the tag to republish the same version.

2. Increase the package version in pyproject.toml, normally by incrementing
   the patch component.

   For example:

   X.Y.Z -> X.Y.(Z+1)

3. Commit the correction.

4. Create and push a tag matching the new package version.

5. Let GitHub Actions publish the new version.


Note
----

- Use X.Y.Z in pyproject.toml.
- Use vX.Y.Z for the Git tag and GitHub release.
- Ensure the tag points to the commit containing version X.Y.Z.
- Never reuse a version already published to PyPI.
- Do not commit PyPI passwords or API tokens.
- Let GitHub Actions publish through Trusted Publishing.
