Auto-release on every source-file commit (continuous deployment, gated) (#28)

Switch the publish workflow from manual-only (workflow_dispatch) to also
fire on push to master when source files change. "Source" is gated to:
  - src/PyDiffGame/**     (the package itself)
  - pyproject.toml        (packaging metadata, deps, classifiers)

Docs / tests / tooling / CI changes do NOT cut a release on their own; a
mixed commit (e.g. src/foo.py + README.md) does. workflow_dispatch stays
available for on-demand publishing.

Three independent loop guards stop the workflow's own "chore: bump
version" commit from re-triggering itself:
  1. The bump commit message contains [skip ci]; GitHub Actions natively
     skips creating a workflow run for such pushes.
  2. Defense-in-depth job-level if: filtering out github-actions[bot] and
     re-checking the commit message.
  3. paths: filter (src changes only) on the trigger.

Add a concurrency group (publish-master, no cancel) so back-to-back
pushes serialize on the git push of the bump commit.

Also fix two pre-existing lint errors (unused import, unsorted imports)
in tools/render_logo.py that would otherwise block CI.


Claude-Session: https://claude.ai/code/session_013KvuS9HKbnZAwwFJyBkyHc

Co-authored-by: Claude <noreply@anthropic.com>

Author: krichelj

.github/workflows/python-publish.yml

@@ -1,9 +1,28 @@
 # Publishes the package to PyPI and creates the matching GitHub Release,
-# auto-incrementing the version each run.
+# auto-incrementing the version when source files change on master.
 #
-# Flow (just run it — Actions -> Upload Python Package -> Run workflow):
+# Triggers:
+#   - push to master that touches SOURCE files (the package or its packaging
+#     metadata) — docs / tests / tooling / CI changes do not cut a release.
+#   - workflow_dispatch: manual trigger remains available for on-demand re-runs
+#     (use this if you ever need to publish despite no source-file changes).
+#
+# Loop prevention: the workflow itself commits a "chore: bump version" commit
+# back to master. Three independent guards stop that commit from re-triggering
+# the workflow:
+#   1. GitHub Actions natively skips push events whose head commit message
+#      contains "[skip ci]" (which the bump commit always does).
+#   2. The bump-version job is guarded with an explicit `if:` so it only runs
+#      for human commits / manual dispatch, never for github-actions[bot].
+#   3. The bump commit message itself contains "[skip ci]" so even if (1) and
+#      (2) ever break, the message still signals "do not republish".
+#
+# Concurrency: serialize runs so two pushes close together don't race on the
+# bump commit's git push.
+#
+# Flow per run:
 #   1. bump-version  : increment the version (carry-at-9 via tools/bump_version.py),
-#                      commit it back to master.
+#                      commit it back to master with [skip ci].
 #   2. release-build : build the dists from the bumped master.
 #   3. pypi-publish  : upload to PyPI via Trusted Publishing (OIDC, no tokens).
 #   4. github-release: create the v<version> GitHub Release with notes + dists.
@@ -13,14 +32,36 @@
 name: Upload Python Package
 
 on:
+  push:
+    branches: [master]
+    # Only publish when source files change. Docs/tests/tooling commits do not
+    # cut a release; mixed commits do (the filter matches if ANY changed file
+    # matches).
+    paths:
+      - 'src/PyDiffGame/**'
+      - 'pyproject.toml'
   workflow_dispatch:
 
 permissions:
   contents: read
 
+concurrency:
+  group: publish-master
+  cancel-in-progress: false
+
 jobs:
   bump-version:
     runs-on: ubuntu-latest
+    # Defense-in-depth loop guard: only release for human commits or manual
+    # dispatch — never for the workflow's own [skip ci] bump commit.
+    if: >-
+      ${{
+        github.event_name == 'workflow_dispatch' ||
+        (
+          github.actor != 'github-actions[bot]' &&
+          !contains(github.event.head_commit.message, '[skip ci]')
+        )
+      }}
     permissions:
       contents: write
     outputs:

CLAUDE.md

@@ -16,11 +16,21 @@
   do not bump it in ordinary PRs — the release run does it.
 
 ## Releasing
-- `Actions -> Upload Python Package -> Run workflow` (on `master`). The workflow
-  auto-increments the version, commits it to `master`, builds with `uv build`,
-  publishes to PyPI via Trusted Publishing (OIDC, no tokens), and creates the matching
-  `v<version>` GitHub Release with notes and the built dists attached. It is idempotent
-  (`skip-existing`).
+- **Continuous deployment, gated on source changes.** Every commit to `master`
+  that touches `src/PyDiffGame/**` or `pyproject.toml` automatically triggers
+  the publish workflow. Docs / tests / tooling / CI changes do **not** trigger
+  a release on their own; mixed commits do.
+- The workflow auto-increments the version (`tools/bump_version.py`), commits
+  the bump to `master` as `chore: bump version to X.Y.Z [skip ci]`, builds with
+  `uv build`, publishes to PyPI via Trusted Publishing (OIDC, no tokens), and
+  creates the matching `v<version>` GitHub Release with notes and the built
+  dists attached. It is idempotent (`skip-existing`).
+- Manual on-demand publish stays available via
+  `Actions -> Upload Python Package -> Run workflow` (`workflow_dispatch`).
+- Three independent guards prevent the bump commit from re-triggering the
+  workflow (an infinite loop): `[skip ci]` in the message (which GitHub Actions
+  natively honors), an explicit job-level `if:` filtering out
+  `github-actions[bot]`, and `paths:` filter scoping to source files.
 
 ## Docs
 - `README.md` is the single canonical readme and is also the PyPI long-description

CONTRIBUTING.md

@@ -41,27 +41,52 @@ they pass locally.
 
 ## Releasing
 
-Publishing a new version is a single automated step — just run the publish
-workflow: **Actions -> Upload Python Package -> Run workflow** (on `master`).
+The project is on **continuous deployment for source changes**: every commit
+to `master` that touches source files automatically cuts a new release.
 
-The run automatically:
+A commit triggers a release when it changes any of:
+
+- `src/PyDiffGame/**` — the package itself
+- `pyproject.toml` — packaging metadata, dependencies, classifiers
+
+Docs (`*.md`, `docs/**`), tests (`tests/**`), tooling (`tools/**`, `.github/**`,
+`.pre-commit-config.yaml`), images and the lock file do **not** trigger a
+release on their own. A mixed commit (e.g. `src/foo.py` + `README.md`) does
+trigger one — the path filter matches if any changed file matches.
+
+When a release-triggering commit lands on `master`, the publish workflow:
 
 1. **Increments the version** with `tools/bump_version.py`, which rolls each
-   component over at 9 (`2.0.9 -> 2.1.0`, `2.9.9 -> 3.0.0`), updating both
-   `pyproject.toml` and `src/PyDiffGame/__init__.py`, and commits the bump to
-   `master`.
+   component over at 9 (`2.0.9 -> 2.1.0`, `2.9.9 -> 3.0.0`), updates both
+   `pyproject.toml` and `src/PyDiffGame/__init__.py`, and commits the bump back
+   to `master` as `chore: bump version to X.Y.Z [skip ci]`.
 2. Builds the distributions with `uv build`.
 3. Uploads them to PyPI via
    [Trusted Publishing](https://docs.pypi.org/trusted-publishers/) (OIDC — no
    tokens or secrets).
 4. Creates a `v<version>` GitHub Release with auto-generated notes and the built
    wheels/sdist attached.
 
+The workflow can also be triggered manually from **Actions -> Upload Python
+Package -> Run workflow** if you ever need to re-run it.
+
 You normally never edit the version by hand. To bump it locally (e.g. to test),
 run `uv run python tools/bump_version.py` (`--dry-run` to preview, `--current`
 to print the current version). The PyPI upload is idempotent (`skip-existing`),
 so re-running the workflow is safe.
 
+### What stops an infinite loop?
+
+The publish workflow itself commits the version bump back to `master`. Three
+independent guards stop that commit from re-triggering the workflow:
+
+1. The bump commit message contains `[skip ci]`, which GitHub Actions natively
+   honors by **not creating a workflow run at all** for that push.
+2. The `bump-version` job has an explicit `if:` that skips when the actor is
+   `github-actions[bot]` or the head-commit message contains `[skip ci]`.
+3. `bump_version.py` is the single source of truth for the version, so a
+   tampered bump commit still wouldn't double-bump.
+
 Thank you for your contribution!
 
 Joshua Shay Kricheli

tools/render_logo.py

@@ -17,8 +17,7 @@
 from pathlib import Path
 
 import numpy as np
-from PIL import Image, ImageChops, ImageDraw, ImageEnhance, ImageFilter
-
+from PIL import Image, ImageChops, ImageEnhance, ImageFilter
 
 ROOT = Path(__file__).resolve().parent.parent
 # Source is the immutable original (red mark + black wordmark) committed