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

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

@@ -45,37 +45,7 @@ All workflows use explicit, fine-grained permissions (principle of least privile
 
 **Trigger:** Manual workflow dispatch
 
-**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):**
+**Permissions:**
 ```yaml
 permissions:
   contents: write
@@ -83,23 +53,33 @@ permissions:
   pull-requests: write
 ```
 
-- `contents: write` - Allows the job to:
-  - Commit version bumps to `pyproject.toml` and `Cargo.toml`
+**Why These Permissions:**
+- `contents: write` - Allows the workflow to:
+  - Commit version bumps to pyproject.toml and Cargo.toml
   - Push commits to the `main` branch
-  - Create and push git tags (e.g., `v0.3.1`)
-  - Create GitHub Releases
+  - Create and push git tags (e.g., `v0.2.0`)
+  - Create GitHub releases
 
-- `issues: write` / `pull-requests: write` - Allows semantic-release to
-  update issue/PR references in generated release notes.
+- `issues: write` - Allows the workflow to:
+  - Update issue references in release notes
+  - Close issues automatically via commit messages
+  - Add labels or comments to issues
 
-**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
+- `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:**
+- **Preflight** builds all release wheels at the workflow SHA (same matrix as post-release wheel builds), in parallel with the CI gate and packaging smoke jobs. If any platform fails, the Create Release job does not run.
+- 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`
 
 **Required Secrets:**
 - `RELEASE_DEPLOY_KEY` (private SSH key for a write-enabled deploy key)
@@ -109,15 +89,15 @@ permissions:
 
 ### 2. Build & Publish (jobs in `release.yml`)
 
-**Trigger:** Part of `release.yml` — all build and publish jobs live in the same workflow file.
+**Trigger:** Part of `release.yml` after the Create Release job (no reusable workflow). Wheel preflight runs in parallel with CI and packaging smoke, before that job.
 
 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, verify-docs:** (default - read-only)
+**For build-wheels, build-sdist, test-wheels:** (default - read-only)
 
-**For promote-pypi job:**
+**For publish-pypi job:**
 ```yaml
 permissions:
   id-token: write
@@ -127,10 +107,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 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
+- Builds wheels for multiple platforms from the release tag
+- Builds source distribution
+- Tests built packages
+- Publishes to PyPI using OIDC authentication
 
 ---
 
@@ -269,7 +249,7 @@ Permission to manage GitHub Pages deployments:
 
 ### Release Completed But Publish/Docs Did Not Run
 
-**Cause:** `release.yml` gates downstream jobs. If CI, packaging smoke, or release creation fails, publish/docs are skipped.
+**Cause:** `release.yml` gates downstream jobs. If CI, packaging smoke, preflight wheel builds, or release creation fails, publish/docs are skipped.
 
 **Solution:**
 - Open the failed `release.yml` run and inspect the first failed job.
@@ -289,18 +269,10 @@ Permission to manage GitHub Pages deployments:
 **Cause:** Missing `id-token: write` permission
 
 **Solution:**
-- Ensure `promote-pypi` job has `id-token: write`
+- Ensure `publish-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 → ferro_orm-0.3.3}/.github/workflows/ci.yml

@@ -171,6 +171,60 @@ jobs:
           name: python-${{ matrix.python-version }}
         continue-on-error: true
 
+  test-python-backend-matrix:
+    name: Python backend matrix (SQLite + Postgres)
+    runs-on: ubuntu-latest
+    services:
+      postgres:
+        image: postgres:17
+        env:
+          POSTGRES_USER: ferro
+          POSTGRES_PASSWORD: ferro
+          POSTGRES_DB: ferro
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd "pg_isready -U ferro -d ferro"
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+    env:
+      FERRO_SUPABASE_URL: postgresql://ferro:ferro@127.0.0.1:5432/ferro?sslmode=disable
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - 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: Set up Rust
+        uses: dtolnay/rust-toolchain@stable
+
+      - name: Cache Rust build
+        uses: Swatinem/rust-cache@v2
+        with:
+          prefix-key: v1
+          cache-on-failure: true
+
+      - name: Install dependencies
+        run: |
+          uv sync --only-group ci-test --no-install-project --python 3.13
+
+      - name: Build Rust extension
+        run: |
+          uv run maturin develop
+
+      - name: Run backend matrix tests
+        run: |
+          uv run pytest -v -m "backend_matrix or postgres_only" --db-backends=sqlite,postgres
+
   check-conventional-commits:
     name: Check Conventional Commits
     runs-on: ubuntu-latest
@@ -220,7 +274,7 @@ jobs:
 
   all-checks:
     name: All Checks Passed
-    needs: [lint-and-format, test-python-pr, test-python-main, test-rust]
+    needs: [lint-and-format, test-python-pr, test-python-main, test-python-backend-matrix, test-rust]
     runs-on: ubuntu-latest
     if: always()
     steps:
@@ -232,6 +286,7 @@ jobs:
           if ! ok "${{ needs.lint-and-format.result }}"; then exit 1; fi
           if ! ok "${{ needs.test-python-pr.result }}"; then exit 1; fi
           if ! ok "${{ needs.test-python-main.result }}"; then exit 1; fi
+          if ! ok "${{ needs.test-python-backend-matrix.result }}"; then exit 1; fi
           if ! ok "${{ needs.test-rust.result }}"; then exit 1; fi
 
           echo "All checks passed!"

{ferro_orm-0.3.1 → ferro_orm-0.3.3}/.github/workflows/publish.yml

@@ -60,6 +60,10 @@ jobs:
 
       - name: Build wheels
         uses: PyO3/maturin-action@v1.48.0
+        env:
+          # ring (via rustls/sqlx): manylinux2014-cross gcc does not define __ARM_ARCH for .S asm.
+          # https://github.com/briansmith/ring/issues/1728
+          CFLAGS_aarch64_unknown_linux_gnu: ${{ matrix.platform.name == 'linux-aarch64' && '-D__ARM_ARCH=8' || '' }}
         with:
           target: ${{ matrix.platform.target }}
           args: --release --out dist --find-interpreter

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

@@ -0,0 +1,374 @@
+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:
+  # Same maturin targets as build-wheels, but against the current ref *before*
+  # semantic-release mutates the repo. Runs in parallel with CI gate and
+  # packaging smoke so the wall-clock pipeline stays shorter.
+  preflight-build-wheels:
+    name: Preflight build wheels (${{ matrix.platform.name }})
+    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: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ github.sha }}
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.13'
+
+      - name: Build wheels (preflight)
+        uses: PyO3/maturin-action@v1.48.0
+        env:
+          # ring (via rustls/sqlx): manylinux2014-cross gcc does not define __ARM_ARCH for .S asm.
+          # https://github.com/briansmith/ring/issues/1728
+          CFLAGS_aarch64_unknown_linux_gnu: ${{ matrix.platform.name == 'linux-aarch64' && '-D__ARM_ARCH=8' || '' }}
+        with:
+          target: ${{ matrix.platform.target }}
+          args: --release --out dist --find-interpreter
+          manylinux: ${{ matrix.platform.manylinux }}
+          sccache: 'true'
+
+  ci-gate:
+    name: CI Gate
+    uses: ./.github/workflows/ci.yml
+
+  packaging-smoke:
+    name: Packaging Smoke Gate
+    uses: ./.github/workflows/packaging-smoke.yml
+
+  release:
+    name: Create Release
+    needs: [ci-gate, packaging-smoke, preflight-build-wheels]
+    runs-on: ubuntu-latest
+    outputs:
+      release_created: ${{ steps.verify_release.outputs.release_created }}
+      release_ref: ${{ steps.release_ref.outputs.release_ref }}
+    permissions:
+      contents: write
+      issues: write
+      pull-requests: write
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          ssh-key: ${{ secrets.RELEASE_DEPLOY_KEY }}
+          persist-credentials: false
+
+      - 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: Set up Rust
+        uses: dtolnay/rust-toolchain@stable
+
+      - name: Cache Rust dependencies
+        uses: Swatinem/rust-cache@v2
+        with:
+          prefix-key: "v1-rust"
+
+      - name: Install dependencies
+        run: |
+          uv sync --only-group release --no-install-project --python 3.13
+
+      - name: Configure Git
+        run: |
+          git config --local user.email "github-actions[bot]@users.noreply.github.com"
+          git config --local user.name "github-actions[bot]"
+          git remote set-url origin "git@github.com:${{ github.repository }}.git"
+
+      - name: Run semantic-release
+        env:
+          # Prefer a PAT so release events can trigger downstream workflows.
+          GH_TOKEN: ${{ secrets.RELEASE_TOKEN || secrets.GITHUB_TOKEN }}
+        run: |
+          # Use the --prerelease flag if requested via manual trigger
+          PRERELEASE_FLAG=""
+          if [ "${{ github.event.inputs.prerelease }}" == "true" ]; then
+            PRERELEASE_FLAG="--prerelease"
+          fi
+
+          # This command will:
+          # 1. Bump version in pyproject.toml and Cargo.toml
+          # 2. Update CHANGELOG.md
+          # 3. Create a commit and push it
+          # 4. Create a tag and push it
+          # 5. Create a GitHub Release (publishing is handled by the wheels/publish workflow)
+          uv run semantic-release version $PRERELEASE_FLAG
+
+      - name: Verify release commit updates changelog
+        id: verify_release
+        shell: bash
+        run: |
+          LAST_SUBJECT="$(git log -1 --pretty=%s)"
+          if [[ "$LAST_SUBJECT" != chore\(release\):* ]]; then
+            echo "No release commit created in this run; skipping changelog validation."
+            echo "release_created=false" >> "$GITHUB_OUTPUT"
+            echo "changelog_validated=skipped" >> "$GITHUB_OUTPUT"
+            echo "release_subject=$LAST_SUBJECT" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+
+          echo "release_created=true" >> "$GITHUB_OUTPUT"
+          echo "release_subject=$LAST_SUBJECT" >> "$GITHUB_OUTPUT"
+
+          CHANGED_FILES="$(git show --name-only --pretty='' HEAD)"
+          if [[ "$CHANGED_FILES" != *"CHANGELOG.md"* ]]; then
+            echo "WARNING: release commit does not include CHANGELOG.md update."
+            echo "Changed files:"
+            echo "$CHANGED_FILES"
+            echo "changelog_validated=missing" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+
+          echo "changelog_validated=passed" >> "$GITHUB_OUTPUT"
+          echo "Validated: release commit includes CHANGELOG.md."
+
+      - name: Capture released ref
+        id: release_ref
+        shell: bash
+        run: |
+          if [[ "${{ steps.verify_release.outputs.release_created }}" != "true" ]]; then
+            echo "release_ref=" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+
+          RELEASE_TAG="$(git tag --points-at HEAD | head -n1)"
+          if [[ -z "$RELEASE_TAG" ]]; then
+            echo "ERROR: expected release tag on HEAD but none was found."
+            exit 1
+          fi
+
+          echo "release_ref=$RELEASE_TAG" >> "$GITHUB_OUTPUT"
+          echo "Using release ref: $RELEASE_TAG"
+
+      - name: Release summary
+        if: always()
+        shell: bash
+        run: |
+          {
+            echo "## Release workflow summary"
+            echo ""
+            echo "- Trigger: \`${{ github.event_name }}\`"
+            echo "- Ref: \`${{ github.ref_name }}\`"
+            echo "- Release commit created: \`${{ steps.verify_release.outputs.release_created || 'unknown' }}\`"
+            echo "- Changelog validation: \`${{ steps.verify_release.outputs.changelog_validated || 'unknown' }}\`"
+            echo "- Release ref: \`${{ steps.release_ref.outputs.release_ref || 'n/a' }}\`"
+            echo "- Last commit subject: \`${{ steps.verify_release.outputs.release_subject || '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: [release]
+    if: needs.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: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ needs.release.outputs.release_ref }}
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.13'
+
+      - name: Build wheels
+        uses: PyO3/maturin-action@v1.48.0
+        env:
+          # ring (via rustls/sqlx): manylinux2014-cross gcc does not define __ARM_ARCH for .S asm.
+          # https://github.com/briansmith/ring/issues/1728
+          CFLAGS_aarch64_unknown_linux_gnu: ${{ matrix.platform.name == 'linux-aarch64' && '-D__ARM_ARCH=8' || '' }}
+        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: [release]
+    if: needs.release.outputs.release_created == 'true'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ needs.release.outputs.release_ref }}
+
+      - 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: [release, build-wheels]
+    if: needs.release.outputs.release_created == 'true'
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ needs.release.outputs.release_ref }}
+
+      - 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())
+          "
+
+  publish-pypi:
+    name: Publish to PyPI
+    needs: [release, build-wheels, build-sdist, test-wheels]
+    if: needs.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 all artifacts
+        uses: actions/download-artifact@v4
+        with:
+          path: dist
+          merge-multiple: true
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          skip-existing: true
+          verbose: true
+
+  deploy-docs:
+    name: Deploy Documentation
+    needs: [release, publish-pypi]
+    if: needs.release.outputs.release_created == 'true'
+    uses: ./.github/workflows/publish-docs.yml
+    permissions:
+      contents: read
+      pages: write
+      id-token: write
+    with:
+      ref: ${{ needs.release.outputs.release_ref }}