ferro-orm 0.2.1__tar.gz → 0.3.1__tar.gz

{ferro_orm-0.2.1 → ferro_orm-0.3.1}/.github/PERMISSIONS.md

@@ -45,7 +45,37 @@ All workflows use explicit, fine-grained permissions (principle of least privile
 
 **Trigger:** Manual workflow dispatch
 
-**Permissions:**
+**Job graph (top to bottom is execution order):**
+
+```
+ci-gate        packaging-smoke
+        \      /
+      prepare-release                 (computes bump, writes release.patch; no pushes)
+     /    |    |    \
+build-wheels build-sdist test-wheels verify-docs
+                  \    |    /
+                promote-pypi           (PyPI Trusted Publishing; first irreversible step)
+                      |
+                 promote-git           (commit bump, push main, tag, create GH Release + assets)
+                      |
+                 promote-docs          (deploys MkDocs site pinned to the new tag)
+```
+
+Nothing is pushed, tagged, or published until every validation job above
+`promote-pypi` has succeeded. PyPI is published first so that if anything
+fails, `main` is never advanced to an "orphan" version.
+
+**Permissions (prepare-release):**
+```yaml
+permissions:
+  contents: read
+  issues: read
+  pull-requests: read
+```
+
+Prepare-release only needs read access because it just computes the bump and uploads a patch artifact — it does not push anything.
+
+**Permissions (promote-git):**
 ```yaml
 permissions:
   contents: write
@@ -53,32 +83,23 @@ permissions:
   pull-requests: write
 ```
 
-**Why These Permissions:**
-- `contents: write` - Allows the workflow to:
-  - Commit version bumps to pyproject.toml and Cargo.toml
+- `contents: write` - Allows the job to:
+  - Commit version bumps to `pyproject.toml` and `Cargo.toml`
   - Push commits to the `main` branch
-  - Create and push git tags (e.g., `v0.2.0`)
-  - Create GitHub releases
+  - Create and push git tags (e.g., `v0.3.1`)
+  - Create GitHub Releases
 
-- `issues: write` - Allows the workflow to:
-  - Update issue references in release notes
-  - Close issues automatically via commit messages
-  - Add labels or comments to issues
+- `issues: write` / `pull-requests: write` - Allows semantic-release to
+  update issue/PR references in generated release notes.
 
-- `pull-requests: write` - Allows the workflow to:
-  - Update PR references in release notes
-  - Close PRs automatically via commit messages
-  - Add labels or comments to PRs
-
-**What It Does:**
-- Analyzes conventional commits
-- Determines next version
-- Updates version in both Python and Rust files
-- Finalizes CHANGELOG.md
-- Creates git tag
-- Creates GitHub release
-- Triggers publish workflow
-- Reports whether release commits include `CHANGELOG.md`
+**What the release flow does:**
+- Analyzes conventional commits since the latest tag (fetched explicitly via `fetch-tags: true`)
+- Fails fast if the computed version collides with an existing tag (indicates a tag-fetch bug)
+- Bumps version in `pyproject.toml` and `Cargo.toml` and finalizes `CHANGELOG.md`
+- Validates the bumped tree across wheel builds, sdist, install smoke tests, and `mkdocs build`
+- Publishes to PyPI before touching `main`
+- Commits bump to `main`, creates the tag, creates the GitHub Release with generated notes, attaches wheels + sdist
+- Deploys the MkDocs site pinned to the new tag
 
 **Required Secrets:**
 - `RELEASE_DEPLOY_KEY` (private SSH key for a write-enabled deploy key)
@@ -88,15 +109,15 @@ permissions:
 
 ### 2. Build & Publish (jobs in `release.yml`)
 
-**Trigger:** Part of `release.yml` after the release job (no reusable workflow).
+**Trigger:** Part of `release.yml` — all build and publish jobs live in the same workflow file.
 
 Build, test, and publish jobs are defined directly in `release.yml` so PyPI Trusted Publishing receives a token with `workflow_ref: release.yml` (reusable workflows are not supported by PyPI).
 
 **Permissions:**
 
-**For build-wheels, build-sdist, test-wheels:** (default - read-only)
+**For build-wheels, build-sdist, test-wheels, verify-docs:** (default - read-only)
 
-**For publish-pypi job:**
+**For promote-pypi job:**
 ```yaml
 permissions:
   id-token: write
@@ -106,10 +127,10 @@ permissions:
 - `id-token: write` - Allows the job to request an OIDC token and authenticate with PyPI using Trusted Publishing.
 
 **What It Does:**
-- Builds wheels for multiple platforms from the release tag
-- Builds source distribution
-- Tests built packages
-- Publishes to PyPI using OIDC authentication
+- Builds wheels for multiple platforms against the patched (bumped) tree
+- Builds source distribution against the patched tree
+- Installs wheels and runs a smoke import + in-memory SQLite check
+- `promote-pypi` publishes the validated wheels + sdist to PyPI via OIDC
 
 ---
 
@@ -268,10 +289,18 @@ Permission to manage GitHub Pages deployments:
 **Cause:** Missing `id-token: write` permission
 
 **Solution:**
-- Ensure `publish-pypi` job has `id-token: write`
+- Ensure `promote-pypi` job has `id-token: write`
 - Verify PyPI trusted publisher is configured correctly
 - Check environment name matches (`pypi`)
 
+### Release says "0.3.0 has already been released!" for a version that was already shipped
+
+**Cause:** `actions/checkout@v4` runs `git fetch --no-tags` by default, even with `fetch-depth: 0`. Without tags, `semantic-release` picks an older baseline tag, computes a minor/patch bump, and lands on the same version number as a prior release.
+
+**Solution:**
+- The `prepare-release` job sets `fetch-tags: true` on its checkout step and then runs a `git describe` vs `semantic-release --print-last-released-tag` comparison as a guard. Both must be present.
+- If this check fails in a run, confirm no one has removed `fetch-tags: true` from the checkout step.
+
 ---
 
 ## Verification

ferro_orm-0.3.1/.github/workflows/release.yml

@@ -0,0 +1,552 @@
+name: Release
+
+on:
+  workflow_dispatch:
+    inputs:
+      prerelease:
+        description: 'Create a pre-release'
+        required: false
+        type: boolean
+        default: false
+
+concurrency:
+  group: release-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  ci-gate:
+    name: CI Gate
+    uses: ./.github/workflows/ci.yml
+
+  packaging-smoke:
+    name: Packaging Smoke Gate
+    uses: ./.github/workflows/packaging-smoke.yml
+
+  # Bump versions and changelog locally only; export a patch so every later job
+  # validates the exact tree that would be released. Nothing is pushed until
+  # promote-* jobs run, after wheels, sdist, tests, and docs all pass.
+  prepare-release:
+    name: Prepare release (no push)
+    needs: [ci-gate, packaging-smoke]
+    runs-on: ubuntu-latest
+    outputs:
+      release_created: ${{ steps.verify_release.outputs.release_created }}
+      release_base_sha: ${{ steps.base_sha.outputs.release_base_sha }}
+      release_tag: ${{ steps.verify_release.outputs.release_tag }}
+      release_version: ${{ steps.verify_release.outputs.release_version }}
+    permissions:
+      contents: read
+      issues: read
+      pull-requests: read
+
+    steps:
+      - name: Record workflow base SHA
+        id: base_sha
+        run: echo "release_base_sha=${{ github.sha }}" >> "$GITHUB_OUTPUT"
+
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          # actions/checkout@v4 passes --no-tags by default, even with
+          # fetch-depth: 0. semantic-release needs tags to pick the right
+          # baseline version; without them it may bump from an older tag and
+          # land on a version that has already been released.
+          fetch-tags: true
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.13'
+
+      - name: Install UV
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Install dependencies
+        run: |
+          uv sync --only-group release --no-install-project --python 3.13
+
+      # Fail fast if the checkout did not materialize tags. Without this guard
+      # semantic-release silently picks an older baseline and can compute an
+      # already-released version (see PSR note: "No release will be made, X has
+      # already been released!").
+      - name: Verify tag visibility
+        env:
+          GH_TOKEN: ${{ secrets.RELEASE_TOKEN || secrets.GITHUB_TOKEN }}
+        run: |
+          set -euo pipefail
+          GIT_LATEST_TAG="$(git describe --tags --abbrev=0 2>/dev/null || echo '')"
+          PSR_LATEST_TAG="$(uv run semantic-release version --print-last-released-tag 2>/dev/null | tail -n1 || echo '')"
+
+          echo "git describe --tags --abbrev=0       -> '${GIT_LATEST_TAG}'"
+          echo "semantic-release --print-last-released-tag -> '${PSR_LATEST_TAG}'"
+
+          if [[ -n "${GIT_LATEST_TAG}" && "${GIT_LATEST_TAG}" != "${PSR_LATEST_TAG}" ]]; then
+            echo "ERROR: git and semantic-release disagree on the latest tag."
+            echo "This usually means actions/checkout did not fetch tags."
+            echo "Confirm 'fetch-tags: true' on the checkout step."
+            exit 1
+          fi
+
+      - name: Run semantic-release (local bump only)
+        env:
+          GH_TOKEN: ${{ secrets.RELEASE_TOKEN || secrets.GITHUB_TOKEN }}
+        run: |
+          PRERELEASE_FLAG=""
+          if [ "${{ github.event.inputs.prerelease }}" == "true" ]; then
+            PRERELEASE_FLAG="--prerelease"
+          fi
+
+          # Writes version files + CHANGELOG only; no commit, push, tag, or VCS
+          # release. --skip-build defers packaging to validation jobs.
+          uv run semantic-release version $PRERELEASE_FLAG \
+            --no-vcs-release --no-tag --no-commit --no-push --skip-build
+
+      - name: Verify release candidate and write patch
+        id: verify_release
+        shell: bash
+        run: |
+          set -euo pipefail
+          # Normalize to a single index-vs-HEAD patch (stable for git apply on runners).
+          git add -A
+          git diff --cached HEAD > release.patch
+
+          if [[ ! -s release.patch ]]; then
+            echo "No semantic version bump in this run (index matches HEAD)."
+            echo "release_created=false" >> "$GITHUB_OUTPUT"
+            echo "changelog_validated=skipped" >> "$GITHUB_OUTPUT"
+            echo "release_tag=" >> "$GITHUB_OUTPUT"
+            echo "release_version=" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+
+          if ! grep -qE '^diff --git a/CHANGELOG\.md b/CHANGELOG\.md' release.patch; then
+            echo "WARNING: expected CHANGELOG.md to change for a release bump."
+            echo "release_created=false" >> "$GITHUB_OUTPUT"
+            echo "changelog_validated=missing" >> "$GITHUB_OUTPUT"
+            echo "release_tag=" >> "$GITHUB_OUTPUT"
+            echo "release_version=" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+
+          VERSION="$(python3 -c "import tomllib; print(tomllib.load(open('pyproject.toml', 'rb'))['project']['version'])")"
+          TAG="v${VERSION}"
+
+          # Final guard: if the tag already exists on the remote, bail before
+          # any irreversible promote-* step runs (PyPI, main push, GH Release).
+          if git ls-remote --tags origin "refs/tags/${TAG}" | grep -q .; then
+            echo "ERROR: tag ${TAG} already exists on the remote."
+            echo "This means semantic-release computed a version that is already released."
+            exit 1
+          fi
+
+          echo "release_created=true" >> "$GITHUB_OUTPUT"
+          echo "changelog_validated=passed" >> "$GITHUB_OUTPUT"
+          echo "release_tag=${TAG}" >> "$GITHUB_OUTPUT"
+          echo "release_version=${VERSION}" >> "$GITHUB_OUTPUT"
+          echo "Prepared ${TAG} as patch against ${{ github.sha }}"
+
+      - name: Upload release patch
+        if: steps.verify_release.outputs.release_created == 'true'
+        uses: actions/upload-artifact@v4
+        with:
+          name: release-patch
+          path: release.patch
+
+      - name: Release summary
+        if: always()
+        shell: bash
+        run: |
+          {
+            echo "## Release workflow summary"
+            echo ""
+            echo "- Trigger: \`${{ github.event_name }}\`"
+            echo "- Base ref: \`${{ github.ref_name }}\` @ \`${{ github.sha }}\`"
+            echo "- Release candidate prepared: \`${{ steps.verify_release.outputs.release_created || 'unknown' }}\`"
+            echo "- Changelog validation: \`${{ steps.verify_release.outputs.changelog_validated || 'unknown' }}\`"
+            echo "- Tag if published: \`${{ steps.verify_release.outputs.release_tag || 'n/a' }}\`"
+          } >> "$GITHUB_STEP_SUMMARY"
+
+  # Build and publish jobs are inlined here (not in a reusable workflow) so that
+  # PyPI Trusted Publishing sees workflow_ref = release.yml. Reusable workflows
+  # are not supported by PyPI Trusted Publishing.
+  build-wheels:
+    name: Build wheels (${{ matrix.platform.name }})
+    needs: [prepare-release]
+    if: needs.prepare-release.outputs.release_created == 'true'
+    runs-on: ${{ matrix.platform.runner }}
+    strategy:
+      fail-fast: false
+      matrix:
+        platform:
+          - name: linux-x86_64
+            runner: ubuntu-latest
+            target: x86_64
+            manylinux: auto
+          - name: linux-aarch64
+            runner: ubuntu-latest
+            target: aarch64
+            manylinux: auto
+          - name: macos-aarch64
+            runner: macos-latest
+            target: aarch64
+            manylinux: ''
+          - name: windows-x64
+            runner: windows-latest
+            target: x64
+            manylinux: ''
+
+    steps:
+      - name: Disable Git CRLF conversion before checkout
+        shell: bash
+        run: git config --global core.autocrlf false
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ needs.prepare-release.outputs.release_base_sha }}
+
+      - name: Download release patch
+        uses: actions/download-artifact@v4
+        with:
+          name: release-patch
+          path: release-patch
+
+      - name: Apply release patch
+        shell: bash
+        run: |
+          git config core.autocrlf false
+          git apply release-patch/release.patch
+          rm -rf release-patch
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.13'
+
+      - name: Build wheels
+        uses: PyO3/maturin-action@v1.48.0
+        with:
+          target: ${{ matrix.platform.target }}
+          args: --release --out dist --find-interpreter
+          manylinux: ${{ matrix.platform.manylinux }}
+          sccache: 'true'
+
+      - name: Upload wheels
+        uses: actions/upload-artifact@v4
+        with:
+          name: wheels-${{ matrix.platform.name }}
+          path: dist/*.whl
+
+  build-sdist:
+    name: Build sdist
+    needs: [prepare-release]
+    if: needs.prepare-release.outputs.release_created == 'true'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Disable Git CRLF conversion before checkout
+        shell: bash
+        run: git config --global core.autocrlf false
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ needs.prepare-release.outputs.release_base_sha }}
+
+      - name: Download release patch
+        uses: actions/download-artifact@v4
+        with:
+          name: release-patch
+          path: release-patch
+
+      - name: Apply release patch
+        shell: bash
+        run: |
+          git config core.autocrlf false
+          git apply release-patch/release.patch
+          rm -rf release-patch
+
+      - name: Build sdist
+        uses: PyO3/maturin-action@v1.48.0
+        with:
+          command: sdist
+          args: --out dist
+
+      - name: Upload sdist
+        uses: actions/upload-artifact@v4
+        with:
+          name: sdist
+          path: dist/*.tar.gz
+
+  test-wheels:
+    name: Test wheels (${{ matrix.os }})
+    needs: [prepare-release, build-wheels]
+    if: needs.prepare-release.outputs.release_created == 'true'
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+    steps:
+      - name: Disable Git CRLF conversion before checkout
+        shell: bash
+        run: git config --global core.autocrlf false
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ needs.prepare-release.outputs.release_base_sha }}
+
+      - name: Download release patch
+        uses: actions/download-artifact@v4
+        with:
+          name: release-patch
+          path: release-patch
+
+      - name: Apply release patch
+        shell: bash
+        run: |
+          git config core.autocrlf false
+          git apply release-patch/release.patch
+          rm -rf release-patch
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.13'
+
+      - name: Download wheels
+        uses: actions/download-artifact@v4
+        with:
+          path: dist
+          pattern: wheels-*
+          merge-multiple: true
+
+      - name: Install wheel
+        shell: bash
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install --find-links dist ferro-orm
+
+      - name: Test import
+        shell: bash
+        run: |
+          python -c "import ferro; print('Ferro imported successfully')"
+
+      - name: Run basic smoke test
+        shell: bash
+        run: |
+          python -c "
+          import asyncio
+          from ferro import Model, FerroField, connect
+          from typing import Annotated
+
+          class TestModel(Model):
+              id: Annotated[int, FerroField(primary_key=True)]
+              name: str
+
+          async def test():
+              await connect('sqlite::memory:')
+              print('Connection test passed')
+
+          asyncio.run(test())
+          "
+
+  verify-docs:
+    name: Verify documentation build
+    needs: [prepare-release]
+    if: needs.prepare-release.outputs.release_created == 'true'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Disable Git CRLF conversion before checkout
+        shell: bash
+        run: git config --global core.autocrlf false
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ needs.prepare-release.outputs.release_base_sha }}
+
+      - name: Download release patch
+        uses: actions/download-artifact@v4
+        with:
+          name: release-patch
+          path: release-patch
+
+      - name: Apply release patch
+        shell: bash
+        run: |
+          git config core.autocrlf false
+          git apply release-patch/release.patch
+          rm -rf release-patch
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.13'
+
+      - name: Install UV
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Install documentation dependencies
+        run: |
+          uv sync --only-group docs --no-install-project --python 3.13
+
+      - name: Build MkDocs site
+        run: |
+          uv run --no-sync mkdocs build
+
+  # ---------------------------------------------------------------------------
+  # Promote phase: every validation above has passed. Irreversible steps now
+  # run in a strict order:
+  #   promote-pypi  -> publishes to PyPI (first irreversible action)
+  #   promote-git   -> commits bump, pushes main, creates tag, creates GH Release
+  #   promote-docs  -> deploys MkDocs site pinned to the new tag
+  # If promote-pypi fails, main is untouched and the run can be re-triggered.
+  # ---------------------------------------------------------------------------
+
+  promote-pypi:
+    name: Publish to PyPI
+    needs: [prepare-release, build-wheels, build-sdist, test-wheels, verify-docs]
+    if: needs.prepare-release.outputs.release_created == 'true'
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/ferro-orm
+    permissions:
+      id-token: write
+    steps:
+      - name: Download sdist
+        uses: actions/download-artifact@v4
+        with:
+          name: sdist
+          path: dist
+
+      - name: Download wheels
+        uses: actions/download-artifact@v4
+        with:
+          pattern: wheels-*
+          path: dist
+          merge-multiple: true
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          skip-existing: true
+          verbose: true
+
+  promote-git:
+    name: Commit, tag, and create GitHub Release
+    needs: [prepare-release, promote-pypi]
+    if: needs.prepare-release.outputs.release_created == 'true'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      issues: write
+      pull-requests: write
+    steps:
+      - name: Disable Git CRLF conversion before checkout
+        shell: bash
+        run: git config --global core.autocrlf false
+
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ needs.prepare-release.outputs.release_base_sha }}
+          fetch-depth: 0
+          fetch-tags: true
+          ssh-key: ${{ secrets.RELEASE_DEPLOY_KEY }}
+          # Required so the deploy key stays loaded for git push below.
+          persist-credentials: true
+
+      - name: Download release patch
+        uses: actions/download-artifact@v4
+        with:
+          name: release-patch
+          path: release-patch
+
+      - name: Apply release patch and push release commit
+        env:
+          VERSION: ${{ needs.prepare-release.outputs.release_version }}
+          TAG: ${{ needs.prepare-release.outputs.release_tag }}
+        run: |
+          set -euo pipefail
+          git config core.autocrlf false
+          git apply release-patch/release.patch
+          rm -rf release-patch
+
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git config user.name "github-actions[bot]"
+          git remote set-url origin "git@github.com:${{ github.repository }}.git"
+
+          # Re-check remote (prepare-release already checked, but the window
+          # between jobs is non-zero).
+          if git ls-remote --tags origin "refs/tags/${TAG}" | grep -q .; then
+            echo "ERROR: tag ${TAG} appeared on the remote between jobs."
+            exit 1
+          fi
+
+          git add -A
+          git commit --author="semantic-release <semantic-release@github.com>" \
+            -m "chore(release): ${VERSION}" \
+            -m "Automatically generated by python-semantic-release"
+          git push origin "HEAD:refs/heads/${{ github.ref_name }}"
+
+          git tag -a "${TAG}" -m "Release ${TAG}"
+          git push origin "refs/tags/${TAG}"
+
+      # semantic-release matches branch config (e.g. branches.main); detached HEAD fails with
+      # "Detached HEAD state cannot match any release groups".
+      - name: Attach HEAD to branch for semantic-release
+        run: git switch -C "${{ github.ref_name }}"
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.13'
+
+      - name: Install UV
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Install dependencies
+        run: |
+          uv sync --only-group release --no-install-project --python 3.13
+
+      # semantic-release publish only uploads assets to an existing GitHub
+      # Release. Create the release with generated notes first, then attach
+      # wheels + sdist from the validation jobs.
+      - name: Download sdist for GitHub Release assets
+        uses: actions/download-artifact@v4
+        with:
+          name: sdist
+          path: dist
+
+      - name: Download wheels for GitHub Release assets
+        uses: actions/download-artifact@v4
+        with:
+          pattern: wheels-*
+          path: dist
+          merge-multiple: true
+
+      - name: Create GitHub Release and upload assets
+        env:
+          GH_TOKEN: ${{ secrets.RELEASE_TOKEN || secrets.GITHUB_TOKEN }}
+        run: |
+          set -euo pipefail
+          TAG="${{ needs.prepare-release.outputs.release_tag }}"
+          uv run semantic-release changelog --post-to-release-tag "$TAG"
+          uv run semantic-release publish --tag "$TAG"
+
+  promote-docs:
+    name: Deploy Documentation
+    needs: [prepare-release, promote-git]
+    if: needs.prepare-release.outputs.release_created == 'true'
+    uses: ./.github/workflows/publish-docs.yml
+    permissions:
+      contents: read
+      pages: write
+      id-token: write
+    with:
+      ref: ${{ needs.prepare-release.outputs.release_tag }}

{ferro_orm-0.2.1 → ferro_orm-0.3.1}/.gitignore

@@ -243,3 +243,4 @@ playground.ipynb
 IMPLEMENTATION.md
 Cargo.lock
 demo.db
+docs/superpowers