feat: add automated releases with python-semantic-release

Analyze conventional commits on every push to main: when a release is
due, semantic-release updates the changelog (insertion flag, history
preserved), commits, tags vX.Y.Z and creates the GitHub release; the
same workflow run then builds, publishes to PyPI via trusted
publishing and deploys the versioned docs. hatch-vcs derives the
package version from the tag, so no version file is bumped. Replaces
the manual tag-push release flow.

Author: raederan

.github/workflows/on-release-main.yml

@@ -1,47 +1,89 @@
-# Release workflow: publishes to PyPI via OIDC trusted publishing.
+# Automated release: python-semantic-release analyzes the conventional
+# commits on main, and when a release is due it updates CHANGELOG.md,
+# commits, tags vX.Y.Z, pushes and creates the GitHub release. hatch-vcs
+# derives the package version from that tag, so no version file is bumped.
+# Publishing happens in this same run: pushes made with GITHUB_TOKEN do
+# not retrigger workflows, so a tag-triggered publish would never fire.
 #
-# Filename and environment name are load-bearing: the trusted publisher
-# configured on PyPI references workflow "on-release-main.yml" and
-# environment "pypi" (no token/secret involved).
-#
-# Docs: dev builds are deployed from main by docs.yml; deploy-docs below
-# publishes the versioned per-release docs (mike -> gh-pages branch).
+# Filename and environment name are load-bearing: the PyPI trusted
+# publisher (OIDC) references workflow "on-release-main.yml" and
+# environment "pypi".
 
 name: release-main
 
 on:
   push:
-    tags: ['v[0-9]*']
+    branches: [main]
+  workflow_dispatch:
+
+# One release run at a time: python-semantic-release pushes commits/tags
+# to main, so overlapping runs would race each other.
+concurrency:
+  group: release
+  cancel-in-progress: false
 
 jobs:
-  publish:
+  release:
     runs-on: ubuntu-latest
     environment:
       name: pypi
     permissions:
-      contents: read
       # required for PyPI trusted publishing (OIDC)
       id-token: write
+      # push the release commit/tag and create the GitHub release (PSR)
+      contents: write
+    outputs:
+      released: ${{ steps.psr.outputs.released }}
+      version: ${{ steps.psr.outputs.version }}
     steps:
-      - uses: actions/checkout@v4
+      - name: Check out
+        uses: actions/checkout@v4
         with:
-          # deep clone incl. tags so hatch-vcs derives the version from the tag
+          # full history: PSR analyzes commits, hatch-vcs needs the tags
           fetch-depth: 0
+          # latest main, not the triggering SHA: runs queued behind the
+          # concurrency group must include release commits pushed by the
+          # previous run, or their own push is rejected
+          ref: main
 
       - name: Set up the environment
         uses: ./.github/actions/setup-python-env
 
+      - name: Version, tag and changelog with python-semantic-release
+        id: psr
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          before=$(git rev-parse HEAD)
+          uv run semantic-release version
+          after=$(git rev-parse HEAD)
+          if [ "$before" != "$after" ]; then
+            ver=$(git tag --points-at HEAD | grep -E '^v[0-9]' | head -1)
+            echo "released=true" >> "$GITHUB_OUTPUT"
+            echo "version=${ver#v}" >> "$GITHUB_OUTPUT"
+            echo "released $ver"
+          else
+            echo "released=" >> "$GITHUB_OUTPUT"
+            echo "no release necessary"
+          fi
+
       - name: Build package distribution files
+        if: steps.psr.outputs.released != ''
         run: uv build
 
       - name: Check package metadata
+        if: steps.psr.outputs.released != ''
         run: uvx twine check dist/*
 
       - name: Publish package
+        if: steps.psr.outputs.released != ''
         run: uv publish --trusted-publishing always
 
   deploy-docs:
-    needs: publish
+    needs: release
+    if: needs.release.outputs.released != ''
     runs-on: ubuntu-latest
     permissions:
       # mike commits the built site to the gh-pages branch
@@ -52,23 +94,23 @@ jobs:
     steps:
       - uses: actions/checkout@v4
         with:
-          # deep clone incl. tags: hatch-vcs needs them and mike needs gh-pages
+          # deep clone incl. the release commit and tags pushed by PSR
           fetch-depth: 0
+          ref: main
 
       - name: Set up the environment
         uses: ./.github/actions/setup-python-env
 
       - name: Configure git identity
         run: |
           git config user.name 'github-actions[bot]'
-          git config user.email 'github-actions[bot]@users.noreply.github.com'
+          git config user.email '41898282+github-actions[bot]@users.noreply.github.com'
 
       - name: Deploy versioned documentation
         env:
-          TAG: ${{ github.ref_name }}
+          VERSION: ${{ needs.release.outputs.version }}
         run: |
-          ver="${TAG#v}"
           # --alias-type=copy keeps /latest/ a real directory instead of a
           # redirect, so machine-readable files stay fetchable there
-          uv run mike deploy --push --alias-type=copy --update-aliases "$ver" latest
+          uv run mike deploy --push --alias-type=copy --update-aliases "$VERSION" latest
           uv run mike set-default --push latest

CHANGELOG.md

@@ -1,29 +1,36 @@
 # Changelog
 
-> **Note:** This file is no longer updated manually. Changes since
-> v0.12.0 are tracked in the
+> **Note:** From here on this file is generated by
+> [python-semantic-release](https://python-semantic-release.readthedocs.io/)
+> from the conventional commit history; do not edit release sections
+> manually. Changes between v0.12.0 and the first generated entry are
+> tracked in the
 > [GitHub Releases](https://github.com/OpenSemanticLab/osw-python/releases).
-> Automated changelog generation (python-semantic-release) is planned;
-> the historical entries below are preserved for reference.
+> The historical entries at the bottom are preserved for reference.
+
+<!-- version list -->
 
 ## Version v0.12.0
- - rework ontology import (BREAKING, see examples/ontology_import.py)
- - add in-memory credentials in CredentialManager
- - fix: 'value is not a valid enumeration member' errors
- - improve namespace detection
- - parallelize get_page
+
+- rework ontology import (BREAKING, see examples/ontology_import.py)
+- add in-memory credentials in CredentialManager
+- fix: 'value is not a valid enumeration member' errors
+- improve namespace detection
+- parallelize get_page
 
 ## Version v0.11.0
- - fix code generator for Statement
- - parallelize page operations
- - add legacy file page migration script
- - refactor search function in wiki_tools
- - add file info to utils
- - refactor WtSite to work directly with CredentialManager
+
+- fix code generator for Statement
+- parallelize page operations
+- add legacy file page migration script
+- refactor search function in wiki_tools
+- add file info to utils
+- refactor WtSite to work directly with CredentialManager
 
 ## Version v0.10.0
- - refactor PagePackage creation
- - add requiredExtensions, requiredPackages
+
+- refactor PagePackage creation
+- add requiredExtensions, requiredPackages
 
 ## Version v0.9.0
 
@@ -79,13 +86,11 @@
 
 - add local slot edit feature
 
-
 ## Version v0.2.0
 
 - rename OSL to OSW
 - add page package feature
 
-
 ## Version v0.1.0
 
 - create package

CONTRIBUTING.md

@@ -25,12 +25,15 @@ locally.
 
 ## Releasing
 
-Maintainers release by pushing a version tag; CI does the rest (build,
-publish to PyPI via trusted publishing, deploy versioned docs):
-
-```bash
-git tag v1.2.0 && git push origin v1.2.0
-```
+Releases are fully automated with
+[python-semantic-release](https://python-semantic-release.readthedocs.io/):
+every push to `main` is analyzed, and conventional commits decide the
+outcome. `fix:` commits trigger a patch release, `feat:` a minor release
+and a `BREAKING CHANGE:` footer (or `!` after the type) a major release;
+other types (`chore:`, `docs:`, `ci:`, ...) release nothing. CI then
+updates the changelog, tags, builds, publishes to PyPI via trusted
+publishing and deploys the versioned docs. No manual version bumping or
+tagging.
 
 ## AI Guidelines
 

Makefile

@@ -45,7 +45,8 @@ clean-build: ## Remove build artifacts
 .PHONY: publish
 publish: ## Publish a release to PyPI (CI-only via OIDC trusted publishing)
 	@echo "Publishing happens in CI via OIDC trusted publishing (on-release-main.yml)."
-	@echo "Push a version tag (v*) to trigger a release."
+	@echo "Releases are cut automatically by python-semantic-release from the"
+	@echo "conventional commits on main; no manual tagging."
 
 .PHONY: docs
 docs: ## Build and serve the documentation locally

docs/dev.md

@@ -116,11 +116,16 @@ strict build that fails on any warning:
 
 ## Releasing
 
-Maintainers release by pushing a version tag; CI builds the package,
-publishes it to PyPI via trusted publishing and deploys the versioned
-docs. The version is derived from the tag by `hatch-vcs`, no manual
-bumping needed:
+Releases are fully automated
+([python-semantic-release](https://python-semantic-release.readthedocs.io/)):
+conventional commits on `main` decide the version bump (`fix:` patch,
+`feat:` minor, `BREAKING CHANGE:`/`!` major), CI updates the changelog,
+tags `vX.Y.Z`, builds, publishes to PyPI via trusted publishing and
+deploys the versioned docs. The package version is derived from the tag
+by `hatch-vcs`; nothing is bumped manually.
+
+To preview what the next release would be:
 
 ```bash
-git tag v1.2.0 && git push origin v1.2.0
+uv run semantic-release --noop version
 ```

pyproject.toml

@@ -122,6 +122,8 @@ dev = [
     "mkdocstrings-python>=1.0.3",
     # docs versioning: zensical-compatible mike fork (same pin as OO-LD/oold-schema)
     "mike @ git+https://github.com/squidfunk/mike.git@2.2.0+zensical-0.1.0",
+    # automated releases + changelog from conventional commits
+    "python-semantic-release>=10.0.0",
 ]
 
 [tool.hatch.build.targets.wheel]
@@ -265,6 +267,28 @@ ignore = [
 [tool.ruff.format]
 preview = true
 
+[tool.semantic_release]
+# No version_toml/version_variables: the package version is derived from
+# the git tag by hatch-vcs, so semantic-release only computes the next
+# version from the conventional commits, updates the changelog, commits,
+# tags (vX.Y.Z) and creates the GitHub release. Publishing to PyPI happens
+# in the same workflow run (on-release-main.yml).
+commit_parser = "conventional"
+tag_format = "v{version}"
+commit_message = "chore(release): v{version} [skip ci]"
+# our history starts at v0.x; without this, PSR would jump a 0.x baseline
+# straight to 1.0.0 (moot at >=1.0.0, kept for copy-paste safety)
+allow_zero_version = true
+exclude_commit_patterns = ['''chore\(release\):.*''']
+
+[tool.semantic_release.changelog]
+# prepend new versions at the insertion flag, keep the manual history below
+mode = "update"
+insertion_flag = "<!-- version list -->"
+
+[tool.semantic_release.changelog.default_templates]
+changelog_file = "CHANGELOG.md"
+
 [tool.ty.environment]
 python = "./.venv"
 python-version = "3.10"