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

ferro_orm-0.2.1/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,43 @@
+---
+name: Bug report
+about: Report a bug or unexpected behavior
+title: "`bug` "
+labels: bug
+assignees: Ox54
+
+---
+
+## Summary
+
+<!-- Brief description of the bug. -->
+
+## Environment
+
+- **Ferro version:** <!-- e.g. 0.1.0 or git commit -->
+- **Python version:**
+- **OS:** <!-- e.g. macOS 14, Ubuntu 22.04 -->
+- **Database:** <!-- e.g. SQLite 3.43, PostgreSQL 15 -->
+
+## Steps to reproduce
+
+1.
+2.
+3.
+
+## Expected behavior
+
+<!-- What should happen. -->
+
+## Actual behavior
+
+<!-- What actually happens. Include error messages or tracebacks if relevant. -->
+
+## Minimal example (optional)
+
+```python
+# Minimal code that reproduces the issue
+```
+
+## Additional context
+
+<!-- Logs, screenshots, or other details that might help. -->

ferro_orm-0.2.1/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,37 @@
+---
+name: Feature request
+about: Suggest a new feature or enhancement for Ferro
+title: "`feat` "
+labels: feature
+assignees: Ox54
+
+---
+
+## Summary
+
+<!-- One or two sentences describing the feature and why it would be useful. -->
+
+## Current state
+
+**Status:** <!-- e.g. Not implemented / Partially implemented -->
+
+<!-- If partially implemented, list what works and what does not. -->
+
+**Documentation references:**
+- <!-- e.g. docs/coming-soon.md, docs/guide/queries.md (lines X–Y) -->
+
+**Current workaround:** <!-- How can users achieve this today, if at all? -->
+
+## Proposed API (examples)
+
+```python
+# Example of how the feature would be used
+```
+
+<!-- Describe how this would integrate with the existing API (query builder, models, etc.). -->
+
+## Acceptance criteria
+
+- [ ]
+- [ ]
+- [ ] Docs updated (e.g. remove from Coming Soon, add to relevant guide).

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

@@ -41,31 +41,9 @@ All workflows use explicit, fine-grained permissions (principle of least privile
 
 ---
 
-### 1. Update Changelog (`update-changelog.yml`)
+### 1. Release (`release.yml`)
 
-**Trigger:** Push to `main` branch
-
-**Permissions:**
-```yaml
-permissions:
-  contents: write
-```
-
-**Why These Permissions:**
-- `contents: write` - Allows the workflow to:
-  - Commit updated CHANGELOG.md back to the repository
-  - Push changes to the `main` branch
-
-**What It Does:**
-- Reads conventional commits since last release
-- Updates the `[Unreleased]` section of CHANGELOG.md
-- Commits and pushes the updated changelog
-
----
-
-### 2. Release (`release.yml`)
-
-**Trigger:** Manual workflow dispatch OR release published
+**Trigger:** Manual workflow dispatch
 
 **Permissions:**
 ```yaml
@@ -100,22 +78,23 @@ permissions:
 - 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)
+- `RELEASE_TOKEN` (recommended PAT for release API actions and downstream workflow triggering, falls back to `GITHUB_TOKEN`)
 
 ---
 
-### 3. Build & Publish (`publish.yml`)
+### 2. Build & Publish (jobs in `release.yml`)
+
+**Trigger:** Part of `release.yml` after the release job (no reusable workflow).
 
-**Trigger:** Workflow call, manual dispatch, or release published
+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/test jobs:** (default - read-only)
-```yaml
-# No explicit permissions needed
-# Uses default read permissions to:
-# - Checkout code
-# - Read repository contents
-```
+**For build-wheels, build-sdist, test-wheels:** (default - read-only)
 
 **For publish-pypi job:**
 ```yaml
@@ -123,6 +102,27 @@ permissions:
   id-token: write
 ```
 
+**Why These 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
+
+---
+
+### 3. Publish Docs (`publish-docs.yml`)
+
+**Trigger:** Workflow call from `release.yml`
+
+**Permissions:**
+```yaml
+permissions:
+  contents: read
+```
+
 **For deploy-docs job:**
 ```yaml
 permissions:
@@ -131,21 +131,13 @@ permissions:
 ```
 
 **Why These Permissions:**
-- `id-token: write` - Allows the workflow to:
-  - Request an OIDC token from GitHub
-  - Authenticate with PyPI using Trusted Publishing
-  - Publish packages without API tokens
-
 - `pages: write` - Allows the workflow to:
   - Deploy the generated MkDocs static site to GitHub Pages
   - Update the Pages deployment for the repository
+- `id-token: write` - Allows secure OIDC auth for Pages deployment
 
 **What It Does:**
-- Builds wheels for multiple platforms
-- Builds source distribution
-- Tests built packages
-- Publishes to PyPI using OIDC authentication
-- Builds MkDocs docs on release
+- Builds MkDocs docs
 - Deploys docs to GitHub Pages
 
 ---
@@ -254,14 +246,22 @@ Permission to manage GitHub Pages deployments:
   - `pull-requests: write` for PR comments
   - `issues: write` for issue comments
 
-### Release Created But Publish Workflow Doesn't Start
+### Release Completed But Publish/Docs Did Not Run
 
-**Cause:** The release was created by a workflow using the default `GITHUB_TOKEN`. GitHub can suppress follow-on workflow triggers for events generated by that token to prevent recursive workflow chains.
+**Cause:** `release.yml` gates downstream jobs. If CI, packaging smoke, or release creation fails, publish/docs are skipped.
 
 **Solution:**
-- Create a repo secret named `RELEASE_TOKEN` (classic PAT or fine-grained PAT) with permission to create releases/tags in this repo.
-- The `release.yml` workflow is configured to prefer `RELEASE_TOKEN` and fall back to `GITHUB_TOKEN`.
-- Re-run the Release workflow after adding the secret.
+- Open the failed `release.yml` run and inspect the first failed job.
+- Re-run `release.yml` after fixing the upstream failure.
+
+### Release Fails to Push to `main` with GH013 Ruleset Error
+
+**Cause:** Repository rules require pull requests for `main`, and the release actor is not allowed to bypass.
+
+**Solution:**
+- Ensure the workflow uses the `RELEASE_DEPLOY_KEY` secret (configured in `release.yml`).
+- In repo rulesets for `main`, add the deploy key actor (or your release bot user) to bypass "Changes must be made through a pull request".
+- Re-run the Release workflow.
 
 ### PyPI Publishing Fails with Authentication Error
 
@@ -278,13 +278,6 @@ Permission to manage GitHub Pages deployments:
 
 To verify permissions are working:
 
-### Test Update Changelog
-```bash
-git commit --allow-empty -m "feat: test changelog workflow"
-git push
-# Check Actions tab - should see commit from github-actions[bot]
-```
-
 ### Test Release
 ```bash
 gh workflow run release.yml
@@ -293,8 +286,8 @@ gh workflow run release.yml
 
 ### Test Publish
 ```bash
-# Triggered automatically by release workflow
-# Or manually: gh workflow run publish.yml
+# Triggered by release.yml after a successful release
+gh run list --workflow=release.yml
 ```
 
 ---
@@ -321,5 +314,5 @@ gh workflow run release.yml
 
 ---
 
-**Last Updated:** 2026-01-27
+**Last Updated:** 2026-02-13
 **Status:** ✅ All workflows properly configured with fine-grained permissions

{ferro_orm-0.1.1 → ferro_orm-0.2.1}/.github/PYPI_CHECKLIST.md

@@ -15,7 +15,7 @@ Use this checklist to track your progress setting up PyPI Trusted Publishing.
 - [ ] Added trusted publisher with correct details:
   - [ ] Owner: `syn54x`
   - [ ] Repository: `ferro-orm`
-  - [ ] Workflow: `publish.yml`
+  - [ ] Workflow: `release.yml` (must be the top-level workflow that runs the job; do not use `publish.yml` when it is called from release.yml)
   - [ ] Environment: `pypi` (optional)
 - [ ] Verified configuration appears in publisher list
 
@@ -33,14 +33,14 @@ Use this checklist to track your progress setting up PyPI Trusted Publishing.
 
 ## Workflow Verification
 
-- [ ] Confirmed `.github/workflows/publish.yml` exists
-- [ ] Verified workflow has `id-token: write` permission
-- [ ] Verified workflow has `environment: pypi` (if using environment)
+- [ ] Confirmed `.github/workflows/release.yml` and `.github/workflows/publish.yml` exist
+- [ ] Verified the job that publishes to PyPI has `id-token: write` (in publish.yml, used by release.yml)
+- [ ] Verified publish-pypi job has `environment: pypi` (if using environment)
 - [ ] All workflows pass pre-commit hooks
 
 ## Testing
 
-- [ ] Test workflow triggered manually (optional)
+- [ ] Test release workflow triggered manually
 - [ ] Reviewed workflow logs for authentication
 - [ ] No OIDC errors in logs
 
@@ -64,14 +64,11 @@ Use this checklist to track your progress setting up PyPI Trusted Publishing.
 ## Quick Commands
 
 ```bash
-# Manual workflow trigger
-gh workflow run publish.yml
-
-# Create a test release
-gh release create v0.1.1 --generate-notes
+# Manual release workflow trigger
+gh workflow run release.yml
 
 # Check workflow status
-gh run list --workflow=publish.yml
+gh run list --workflow=release.yml
 
 # Install and test
 pip install ferro-orm

{ferro_orm-0.1.1 → ferro_orm-0.2.1}/.github/PYPI_SETUP.md

@@ -61,9 +61,10 @@ If you want to reserve the package name before publishing:
    PyPI Project Name: ferro-orm
    Owner: syn54x
    Repository name: ferro-orm
-   Workflow filename: publish.yml
+   Workflow filename: release.yml
    Environment name: pypi (optional but recommended)
    ```
+   **Important:** Use `release.yml`, not `publish.yml`. The release workflow calls publish.yml; PyPI's OIDC token reflects the top-level workflow (release.yml), so the trusted publisher must match.
 
 4. **Click "Add"**
 
@@ -86,9 +87,10 @@ If you want to reserve the package name before publishing:
    ```
    Owner: syn54x
    Repository: ferro-orm
-   Workflow: publish.yml
+   Workflow: release.yml
    Environment: pypi (optional)
    ```
+   Use `release.yml` (the workflow that triggers the run). Do not use `publish.yml` when it is invoked via workflow_call from release.yml, or uploads will fail with "Build Config URI does not match expected Trusted Publisher".
 
 6. **Click "Add"**
 
@@ -103,7 +105,7 @@ After adding the trusted publisher, you should see:
 
 Owner:        syn54x
 Repository:   ferro-orm
-Workflow:     publish.yml
+Workflow:     release.yml
 Environment:  pypi
 ```
 
@@ -175,7 +177,7 @@ Before doing a real release, test the workflow:
 
 2. **Trigger the workflow manually:**
    ```bash
-   gh workflow run publish.yml
+   gh workflow run release.yml
    ```
 
 3. **Check the logs:**
@@ -208,6 +210,12 @@ Before doing a real release, test the workflow:
 
 ## Troubleshooting
 
+### Error: "Certificate's Build Config URI ... does not match expected Trusted Publisher (publish.yml @ ...)"
+
+**Cause:** PyPI Trusted Publishing uses the **top-level** workflow for OIDC. This repo runs `publish.yml` via `workflow_call` from `release.yml`, so the token identifies `release.yml`, not `publish.yml`. If PyPI is configured for `publish.yml`, uploads fail.
+
+**Solution:** On PyPI, set the trusted publisher **Workflow** to `release.yml` (not `publish.yml`). Update or add the publisher: Owner `syn54x`, Repository `ferro-orm`, Workflow **release.yml**, Environment `pypi` (optional).
+
 ### Error: "Trusted publishing authentication failed"
 
 **Cause:** OIDC token is rejected by PyPI
@@ -216,7 +224,7 @@ Before doing a real release, test the workflow:
 1. Verify all fields match exactly on PyPI:
    - Owner name (case-sensitive)
    - Repository name (case-sensitive)
-   - Workflow filename (must include `.yml`)
+   - Workflow filename: use **release.yml** (the workflow that starts the run)
    - Environment name (if specified)
 
 2. Check GitHub environment exists:
@@ -241,10 +249,9 @@ Before doing a real release, test the workflow:
 **Cause:** PyPI can't find the workflow file
 
 **Solutions:**
-1. Ensure `publish.yml` exists in `.github/workflows/`
-2. Verify filename matches exactly (case-sensitive)
+1. Ensure `release.yml` exists in `.github/workflows/` (this is the workflow PyPI should reference)
+2. Verify the workflow filename on PyPI matches exactly (case-sensitive): `release.yml`
 3. Check workflow is committed to `main` branch
-4. Workflow must be in the repository (not a reusable workflow)
 
 ### Error: "Environment not found"
 
@@ -318,7 +325,7 @@ After completing setup, verify:
 - [ ] PyPI trusted publisher configured
 - [ ] GitHub environment `pypi` created (if using)
 - [ ] Workflow permissions set to read/write
-- [ ] Workflow file `publish.yml` exists
+- [ ] Workflow file `release.yml` exists (trusted publisher must use this name)
 - [ ] Workflow has `id-token: write` permission
 - [ ] Test workflow runs successfully
 - [ ] Can authenticate with PyPI (check logs)
@@ -342,7 +349,7 @@ After completing setup, verify:
 Project: ferro-orm
 Owner: syn54x
 Repository: ferro-orm
-Workflow: publish.yml
+Workflow: release.yml
 Environment: pypi (optional)
 ```
 

ferro_orm-0.2.1/.github/pull_request_template.md

@@ -0,0 +1,36 @@
+## Description
+
+<!-- What problem does this PR solve? Why is this change needed? -->
+
+## Changes
+
+-
+-
+-
+
+## Bridge and Schema Impact
+
+<!-- Complete if this PR touches model/schema/FFI behavior -->
+
+- [ ] No Rust/Python bridge changes
+- [ ] Python model/schema changed
+- [ ] Rust core or SQL generation changed
+- [ ] `src/ferro/_core.pyi` updated (if needed)
+- [ ] Integration test added first for new behavior
+
+## Migration / Breaking Changes
+
+- [ ] No breaking changes
+- [ ] Breaking changes included (details below)
+
+<!-- If breaking, describe user impact and upgrade path -->
+
+## Documentation and Changelog
+
+- [ ] No docs update needed
+- [ ] Docs updated (README/docs/inline docs)
+- [ ] Changelog entry needed
+
+## Related Issues
+
+<!-- Example: Closes #123 -->

{ferro_orm-0.1.1 → ferro_orm-0.2.1}/.github/workflows/ci.yml

@@ -1,6 +1,7 @@
 name: CI
 
 on:
+  workflow_call:
   pull_request:
     branches: [main]
   push:
@@ -53,11 +54,11 @@ jobs:
 
       - name: Install dependencies
         run: |
-          uv sync --group dev
+          uv sync --only-group ci-lint --no-install-project --python 3.13
 
       - name: Run all pre-commit hooks
         run: |
-          uv run prek run --all-files
+          uv run --no-sync --python 3.13 prek run --all-files
 
   test-rust:
     name: Rust tests
@@ -108,7 +109,7 @@ jobs:
 
       - name: Install dependencies
         run: |
-          uv sync --group dev
+          uv sync --only-group ci-test --no-install-project --python 3.13
 
       - name: Build Rust extension
         run: |
@@ -151,7 +152,7 @@ jobs:
 
       - name: Install dependencies
         run: |
-          uv sync --group dev
+          uv sync --only-group ci-test --no-install-project --python ${{ matrix.python-version }}
 
       - name: Build Rust extension
         run: |
@@ -170,55 +171,6 @@ jobs:
           name: python-${{ matrix.python-version }}
         continue-on-error: true
 
-  packaging-smoke:
-    name: Packaging smoke check (${{ matrix.platform.name }})
-    # Only run the cross-OS packaging check on main / manual.
-    if: github.event_name != 'pull_request'
-    runs-on: ${{ matrix.platform.runner }}
-    strategy:
-      fail-fast: false
-      matrix:
-        platform:
-          - name: linux
-            runner: ubuntu-latest
-            target: x86_64
-            manylinux: auto
-          - name: macos
-            runner: macos-latest
-            target: aarch64
-            manylinux: ''
-          - name: windows
-            runner: windows-latest
-            target: x64
-            manylinux: ''
-    steps:
-      - name: Checkout repository
-        uses: actions/checkout@v4
-
-      - name: Set up Python
-        uses: actions/setup-python@v5
-        with:
-          python-version: '3.13'
-
-      - name: Build wheel
-        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: Install wheel
-        shell: bash
-        run: |
-          python -m pip install --upgrade pip
-          python -m pip install --find-links dist ferro-orm
-
-      - name: Import check
-        shell: bash
-        run: |
-          python -c "import ferro; print('Ferro imported successfully')"
-
   check-conventional-commits:
     name: Check Conventional Commits
     runs-on: ubuntu-latest
@@ -258,7 +210,7 @@ jobs:
             fi
 
             echo "Checking commit: $MESSAGE"
-            if ! uv run cz check --commit-msg-file <(git log -1 --pretty=format:"%s%n%n%b" $commit); then
+            if ! uv run --no-sync --python 3.13 cz check --commit-msg-file <(git log -1 --pretty=format:"%s%n%n%b" $commit); then
               echo "❌ Commit message does not follow conventional format: $MESSAGE"
               exit 1
             fi
@@ -268,7 +220,7 @@ jobs:
 
   all-checks:
     name: All Checks Passed
-    needs: [lint-and-format, test-python-pr, test-python-main, test-rust, packaging-smoke]
+    needs: [lint-and-format, test-python-pr, test-python-main, test-rust]
     runs-on: ubuntu-latest
     if: always()
     steps:
@@ -281,6 +233,5 @@ jobs:
           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-rust.result }}"; then exit 1; fi
-          if ! ok "${{ needs.packaging-smoke.result }}"; then exit 1; fi
 
           echo "All checks passed!"

ferro_orm-0.2.1/.github/workflows/packaging-smoke.yml

@@ -0,0 +1,62 @@
+name: Packaging Smoke
+
+on:
+  workflow_call:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+concurrency:
+  group: packaging-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  packaging-smoke:
+    name: Packaging smoke check (${{ matrix.platform.name }})
+    runs-on: ${{ matrix.platform.runner }}
+    strategy:
+      fail-fast: false
+      matrix:
+        platform:
+          - name: linux
+            runner: ubuntu-latest
+            target: x86_64
+            manylinux: auto
+          - name: macos
+            runner: macos-latest
+            target: aarch64
+            manylinux: ''
+          - name: windows
+            runner: windows-latest
+            target: x64
+            manylinux: ''
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.13'
+
+      - name: Build wheel
+        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: Install wheel
+        shell: bash
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install --find-links dist ferro-orm
+
+      - name: Import check
+        shell: bash
+        run: |
+          python -c "import ferro; print('Ferro imported successfully')"

{ferro_orm-0.1.1 → ferro_orm-0.2.1}/.github/workflows/publish-docs.yml

@@ -2,6 +2,12 @@ name: Publish Docs
 
 on:
   workflow_dispatch:
+  workflow_call:
+    inputs:
+      ref:
+        description: Git ref (branch, tag, or SHA) to build docs from
+        required: true
+        type: string
 
 concurrency:
   group: docs-${{ github.workflow }}-${{ github.ref }}
@@ -17,6 +23,8 @@ jobs:
     steps:
       - name: Checkout repository
         uses: actions/checkout@v4
+        with:
+          ref: ${{ inputs.ref }}
 
       - name: Set up Python
         uses: actions/setup-python@v5
@@ -30,11 +38,11 @@ jobs:
 
       - name: Install documentation dependencies
         run: |
-          uv sync --group dev
+          uv sync --only-group docs --no-install-project --python 3.13
 
       - name: Build MkDocs site
         run: |
-          uv run mkdocs build
+          uv run --no-sync mkdocs build
 
       - name: Upload Pages artifact
         uses: actions/upload-pages-artifact@v3