ci(workflows): add semantic-release pipeline and PR commit linting

owenthcarey · owenthcarey · commit 0711683f5b56 · 2026-03-05T00:35:16.000-08:00
diff --git a/.commitlintrc.yml b/.commitlintrc.yml
@@ -0,0 +1,30 @@
+extends:
+  - '@commitlint/config-conventional'
+
+rules:
+  type-enum:
+    - 2
+    - always
+    - - build
+      - chore
+      - ci
+      - docs
+      - feat
+      - fix
+      - perf
+      - refactor
+      - revert
+      - style
+      - test
+  scope-case:
+    - 0
+  subject-case:
+    - 0
+  header-max-length:
+    - 1
+    - always
+    - 100
+  body-max-line-length:
+    - 0
+  footer-max-line-length:
+    - 0
diff --git a/.github/workflows/pr-lint.yml b/.github/workflows/pr-lint.yml
@@ -0,0 +1,46 @@
+name: PR Lint
+
+on:
+  pull_request:
+    types: [opened, edited, synchronize, reopened]
+
+permissions:
+  pull-requests: read
+
+jobs:
+  pr-title:
+    name: PR title (Conventional Commits)
+    runs-on: ubuntu-latest
+    steps:
+      - name: Validate PR title
+        uses: amannn/action-semantic-pull-request@v5
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        with:
+          types: |
+            build
+            chore
+            ci
+            docs
+            feat
+            fix
+            perf
+            refactor
+            revert
+            style
+            test
+          requireScope: false
+          subjectPattern: ^[a-z].+[^.]$
+          subjectPatternError: |
+            Subject "{subject}" must start with a lowercase letter and must not
+            end with a period.
+            Example: "feat(cli): add init subcommand"
+
+  commits:
+    name: Commit messages
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: wagoid/commitlint-github-action@v6
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
@@ -1,31 +1,77 @@
-name: Release to PyPI
+name: Release
 
 on:
   push:
-    tags:
-      - 'v*.*.*'
+    branches: [main]
+  workflow_dispatch:
+
+# ┌─────────────────────────────────────────────────────────────────┐
+# │ DRAFT_RELEASE                                                   │
+# │                                                                 │
+# │  "true"  → GitHub Releases are created as drafts and PyPI       │
+# │            publishing is skipped (burn-in / review period).     │
+# │  "false" → GitHub Releases are published immediately and the    │
+# │            package is uploaded to PyPI.                         │
+# │                                                                 │
+# │ Flip to "false" once you have verified the release output.      │
+# └─────────────────────────────────────────────────────────────────┘
+env:
+  DRAFT_RELEASE: "true"
 
 jobs:
-  build-and-publish:
+  release:
+    name: Semantic Release
     runs-on: ubuntu-latest
+    if: >-
+      github.event_name == 'workflow_dispatch' ||
+      !startsWith(github.event.head_commit.message, 'chore(release):')
+    concurrency:
+      group: release
+      cancel-in-progress: false
     permissions:
-      contents: read
+      contents: write
       id-token: write
+
     steps:
       - name: Checkout
         uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
 
       - name: Set up Python
         uses: actions/setup-python@v5
         with:
-          python-version: '3.9'
+          python-version: '3.12'
+
+      - name: Install build tools
+        run: python -m pip install -U pip build
+
+      - name: Python Semantic Release
+        id: release
+        uses: python-semantic-release/python-semantic-release@v9
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Build package
+        if: steps.release.outputs.released == 'true'
+        run: python -m build
 
-      - name: Build sdist and wheel
+      - name: Create GitHub Release
+        if: steps.release.outputs.released == 'true'
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         run: |
-          python -m pip install -U pip build
-          python -m build
+          if [ "$DRAFT_RELEASE" = "true" ]; then
+            DRAFT_FLAG="--draft"
+          fi
+          gh release create "${{ steps.release.outputs.tag }}" \
+            ${DRAFT_FLAG:-} \
+            --title "${{ steps.release.outputs.tag }}" \
+            --generate-notes \
+            dist/*
 
-      - name: Publish package to PyPI
+      - name: Publish to PyPI
+        if: steps.release.outputs.released == 'true' && env.DRAFT_RELEASE != 'true'
         uses: pypa/gh-action-pypi-publish@release/v1
         with:
           skip-existing: true
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -205,19 +205,26 @@ Co-authored-by: Name <email>
 
 ## Pull request checklist
 
+- PR title: Conventional Commits format (CI-enforced by `pr-lint.yml`).
 - Tests: added/updated; `pytest` passes.
 - Lint/format: `ruff check .`, `black` pass.
-- Docs: update `README.md` and any Django docs pages if behavior changes.
+- Docs: update `README.md` if behavior changes.
 - Templates: update `templates/` if generator output changes.
 - No generated artifacts committed.
 
 ## Versioning and releases
 
-- The library version is tracked in `pyproject.toml` (`project.version`). Use SemVer.
-- Workflow:
-  - Contributors: branch off `main` (or `dev` if used) and open PRs.
-  - Maintainer (release): bump version, tag, and publish to PyPI.
-  - Tag on `main`: `git tag -a vX.Y.Z -m "Release vX.Y.Z" && git push --tags`.
+- The version is tracked in `pyproject.toml` (`project.version`) and mirrored in `src/pythonnative/__init__.py` as `__version__`. Both files are updated automatically by [python-semantic-release](https://python-semantic-release.readthedocs.io/).
+- **Automated release pipeline** (on every merge to `main`):
+  1. `python-semantic-release` scans Conventional Commit messages since the last tag.
+  2. It determines the next SemVer bump: `feat` → **minor**, `fix`/`perf` → **patch**, `BREAKING CHANGE` → **major** (minor while version < 1.0).
+  3. Version files are updated, `CHANGELOG.md` is generated, and a tagged release commit (`chore(release): vX.Y.Z`) is pushed.
+  4. A GitHub Release is created with auto-generated release notes and the built sdist/wheel attached.
+  5. When drafts are disabled, the package is also published to PyPI via Trusted Publishing.
+- **Draft / published toggle**: the `DRAFT_RELEASE` variable at the top of `.github/workflows/release.yml` controls release mode. Set to `"true"` (the default) for draft GitHub Releases with PyPI publishing skipped; flip to `"false"` to publish releases and upload to PyPI immediately.
+- Commit types that trigger a release: `feat` (minor), `fix` and `perf` (patch), `BREAKING CHANGE` (major). All other types (`build`, `chore`, `ci`, `docs`, `refactor`, `revert`, `style`, `test`) are recorded in the changelog but do **not** trigger a release on their own.
+- Tag format: `v`-prefixed (e.g., `v0.4.0`).
+- Manual version bumps are no longer needed — just merge PRs with valid Conventional Commit titles. For ad-hoc runs, use the workflow's **Run workflow** button (`workflow_dispatch`).
 
 ### Branch naming (suggested)
 
@@ -249,6 +256,13 @@ release/v0.2.0
 hotfix/cli-regression
 ```
 
+### CI
+
+- **CI** (`ci.yml`): runs formatter, linter, type checker, and tests on every push and PR.
+- **PR Lint** (`pr-lint.yml`): validates the PR title against Conventional Commits format (protects squash merges) and checks individual commit messages via commitlint (protects rebase merges). Recommended: add the **PR title** job as a required status check in branch-protection settings.
+- **Release** (`release.yml`): runs on merge to `main`; computes version, generates changelog, tags, creates GitHub Release, and (when `DRAFT_RELEASE` is `"false"`) publishes to PyPI.
+- **Docs** (`docs.yml`): deploys documentation to GitHub Pages on push to `main`.
+
 ## Security and provenance
 
 - Avoid bundling secrets or credentials in templates or code.
diff --git a/pyproject.toml b/pyproject.toml
@@ -88,3 +88,30 @@ ignore = []
 [tool.black]
 line-length = 120
 target-version = ['py39']
+
+# ── Semantic Release ────────────────────────────────────────────────
+
+[tool.semantic_release]
+version_toml = ["pyproject.toml:project.version"]
+version_variables = ["src/pythonnative/__init__.py:__version__"]
+commit_message = "chore(release): v{version}"
+tag_format = "v{version}"
+major_on_zero = false
+
+[tool.semantic_release.branches.main]
+match = "main"
+prerelease = false
+
+[tool.semantic_release.changelog]
+changelog_file = "CHANGELOG.md"
+exclude_commit_patterns = [
+    "^chore\\(release\\):",
+]
+
+[tool.semantic_release.commit_parser_options]
+allowed_tags = [
+    "build", "chore", "ci", "docs", "feat", "fix",
+    "perf", "refactor", "revert", "style", "test",
+]
+minor_tags = ["feat"]
+patch_tags = ["fix", "perf"]
