mahmoud/face/release

Release face

face uses CalVer: YY.MINOR.MICRO (e.g. 26.0.1). The version lives in face/__init__.py as a __version__ literal string. During development it carries a dev suffix (e.g. 26.0.1dev). Flit reads this at build time.

Tags use the v prefix (e.g. v26.0.1, NOT 26.0.1). The publish workflow triggers on tags matching v[0-9]*.[0-9]*.[0-9]*.

Pre-flight checks

Before starting, verify ALL of these:

1. Working tree is clean (git status shows nothing dirty/staged)
2. You are on master branch
3. face/__init__.py has a dev suffix on __version__
4. All tests pass: tox -p auto (or at minimum pytest face/test/ -v)
5. Check what is actually published on PyPI: https://pypi.org/project/face/

PyPI is canonical. If the intended version already exists on PyPI, it cannot be re-released -- bump to the next version instead. If a local/GitHub tag exists for a version that is NOT on PyPI, the prior release failed and should be retried (see "Failed release" under Error recovery).

If any check fails, stop and report. Do not proceed with a dirty tree or failing tests.

Release steps

1. Determine the release version

Read __version__ from face/__init__.py. Strip the dev suffix. Example: 26.0.1dev becomes 26.0.1.

Ask the user to confirm the version. If they want a different version (e.g. bumping minor instead of micro), use that instead.

2. Update version for release

Edit face/__init__.py: remove the dev suffix from __version__.

# Before
__version__ = '26.0.1dev'
# After
__version__ = '26.0.1'

3. Update CHANGELOG.md

Add a new section at the top of CHANGELOG.md (below the # face Changelog heading) for the release version. Use this format:

## 26.0.1
 
_(Month Day, Year)_
 
-First change description
-Second change description

To determine what changed, review the commits since the last tag:

git log $(git describe --tags --abbrev=0)..HEAD --pretty=format:'%s' --no-merges

Summarize the user-facing changes as concise bullet points. Omit version bump commits and other release-mechanical commits. Ask the user to confirm or adjust the changelog entry.

4. Commit the release

git commit -am "face version 26.0.1"

Use the exact format face version X.Y.Z for the commit message.

5. Tag the release

git tag -a v26.0.1 -m "short summary of key changes in this release"

Tags use the v prefix. The tag message should be a short, lowercase, descriptive summary of the release (not just the version number). Examples:

• "migrate to flit, expand test coverage, add CI"
• "python 3.10-3.14 support, windows fixes"
• "modernize build system, drop python 3.8/3.9"

6. Bump to next dev version

Increment the micro version and add dev suffix:

__version__ = '26.0.2dev'

7. Commit the dev bump

git commit -am "bump version to 26.0.2dev"

8. Push

git push origin master --tags

This triggers two GitHub Actions workflows:

• Tests (on the push to master)
• Publish to PyPI (on the tag)

The publish workflow builds the package with build-and-inspect-python-package, which lints the wheel contents (check-wheel-contents) and the PyPI README (twine check --strict), and prints SDist and wheel content trees into the job summary. It then validates that the version from the built package metadata matches the tag (after stripping the v prefix) and contains no dev suffix; if either check fails, publishing is blocked. The built packages are uploaded as an artifact named Packages, which the publish job downloads.

The same action runs as the Package job in tests.yml on every push and pull request, so packaging errors normally surface long before release day.

The pypi deployment environment has a 5-minute wait timer. The publish job will show status: waiting during this period — it auto-approves after the timer expires (self-approval via gh api is blocked by GitHub when the push actor is also the required reviewer).

9. Create GitHub release

gh release create vX.Y.Z --title "vX.Y.Z" --notes "<changelog entries>"

Use the changelog bullet points as the release notes body. Include a **Full Changelog** link comparing the previous tag to the new one: https://github.com/mahmoud/face/compare/vPREV...vNEW.

Post-publish verification

After pushing, wait ~2 minutes for PyPI propagation, then verify in a temporary virtualenv outside the repo (to avoid the local source tree shadowing the installed package):

python3 -m venv /tmp/face-verify && source /tmp/face-verify/bin/activate
pip install face==26.0.1 --index-url https://pypi.org/simple/
cd /tmp  # MUST leave repo root so local face/ does not shadow the install
python -c "import face; print(face.__version__)"
# Should print: 26.0.1
deactivate && rm -rf /tmp/face-verify

If --index-url fails with 404, wait another minute and retry. PyPI CDN propagation can take 1-5 minutes.

Report the results to the user.

Error recovery

• Failed release (tag exists locally/on GitHub but not on PyPI): PyPI is

the source of truth. Delete the stale tag locally and on the remote: ``bash git tag -d vX.Y.Z git push origin :refs/tags/vX.Y.Z # if it was pushed ` Then check __version__ in face/__init__.py. If it was already bumped past the failed release (e.g. X.Y.(Z+1)dev), reset it to X.Y.Zdev` so the release flow strips the suffix to the correct version. Amend or revert the bump commit as needed, then restart the release from step 1.

• Wrong version tagged: git tag -d vX.Y.Z && git push origin :refs/tags/vX.Y.Z

then fix and re-tag.

• Publish workflow failed: Check the GitHub Actions log. Common causes:

version mismatch, dev suffix present, PyPI trusted publisher not configured.

• Tests fail after publish: The package is already on PyPI. File an issue,

fix forward with a patch release.