feat: address migration gaps (WIP)

.github/workflows/cd-monorepo.yml

@@ -146,22 +146,38 @@ jobs:
           git config user.name "github-actions[bot]"
           git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
 
+      # The branch already holds the version to release. The bump happens after
+      # the publish, so the version on the branch names an unreleased version
+      - name: Read the version to release
+        run: |
+          git pull
+          VERSION=$(python3 syft_client/version.py)
+          echo "VERSION=$VERSION" >> $GITHUB_ENV
+          echo "Releasing syft-client $VERSION"
+
+      # Artifacts live inside the package, so they must be committed before the
+      # build. Re-running the export writes nothing when they already exist.
+      - name: Freeze release artifacts
+        run: |
+          just export-release-artifacts
+          git add syft_client/migrations/history
+          git diff --cached --quiet || \
+            git commit -m "Freeze syft-client v${{ env.VERSION }} release artifacts"
+
       - name: Upload to PyPI
         id: publish
         env:
           TWINE_USERNAME: __token__
           TWINE_PASSWORD: ${{ secrets.PYPI_PASS_SYFT_CLIENT }}
         run: |
-          git pull
-          just bump-and-publish ${{ inputs.bump_type }}
-          VERSION=$(python3 syft_client/version.py)
-          echo "VERSION=$VERSION" >> $GITHUB_ENV
-          echo "version=$VERSION" >> $GITHUB_OUTPUT
+          just publish
+          echo "version=${{ env.VERSION }}" >> $GITHUB_OUTPUT
 
-      # bump and publish already does committing
-      - name: Push changes to syft-client repo
+      # The tag must name the published version, so it is created before the bump.
+      - name: Tag the release, then bump for the next one
         run: |
           git tag "syft-client/v${{ env.VERSION }}"
+          just bump ${{ inputs.bump_type }}
           git push origin --follow-tags
 
   post-release-tests:

.github/workflows/cd-syft-bg.yml

@@ -43,16 +43,15 @@ jobs:
           git config user.name "github-actions[bot]"
           git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
 
-      - name: Bump version
+      # The branch already holds the version to release. The bump happens after
+      # the publish, so the version on the branch always names an unreleased
+      # version while people develop.
+      - name: Read the version to release
         run: |
           git pull
-          pip install packaging
-          OUTPUT=$(python scripts/bump_version.py syft-bg ${{ inputs.bump_type }})
-          VERSION=$(echo "$OUTPUT" | sed -n '1p')
-          MODIFIED=$(echo "$OUTPUT" | sed -n '2p')
+          VERSION=$(python -c "import tomllib; print(tomllib.load(open('packages/syft-bg/pyproject.toml','rb'))['project']['version'])")
           echo "VERSION=$VERSION" >> $GITHUB_ENV
-          echo "MODIFIED=$MODIFIED" >> $GITHUB_ENV
-          echo "Bumped syft-bg to $VERSION (modified: $MODIFIED)"
+          echo "Releasing syft-bg $VERSION"
 
       - name: Build package
         working-directory: packages/syft-bg
@@ -65,9 +64,14 @@ jobs:
           TWINE_PASSWORD: ${{ secrets.PYPI_PASS_SYFT_BG }}
         run: uvx twine upload --verbose dist/*
 
-      - name: Commit and tag
+      # The tag must name the published version, so it is created before the bump.
+      - name: Tag the release, then bump for the next one
         run: |
-          git add ${{ env.MODIFIED }}
-          git commit -m "Release syft-bg v${{ env.VERSION }}"
           git tag "syft-bg/v${{ env.VERSION }}"
+          pip install packaging
+          OUTPUT=$(python scripts/bump_version.py syft-bg ${{ inputs.bump_type }} --dependents published)
+          NEXT=$(echo "$OUTPUT" | sed -n '1p')
+          MODIFIED=$(echo "$OUTPUT" | sed -n '2p')
+          git add $MODIFIED
+          git commit -m "Bump syft-bg to $NEXT for the next release"
           git push origin --follow-tags

.github/workflows/cd-syft-dataset.yml

@@ -43,16 +43,24 @@ jobs:
           git config user.name "github-actions[bot]"
           git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
 
-      - name: Bump version
+      # The branch already holds the version to release. The bump happens after
+      # the publish, so the version on the branch always names an unreleased
+      # version while people develop.
+      - name: Read the version to release
         run: |
           git pull
-          pip install packaging
-          OUTPUT=$(python scripts/bump_version.py syft-dataset ${{ inputs.bump_type }})
-          VERSION=$(echo "$OUTPUT" | sed -n '1p')
-          MODIFIED=$(echo "$OUTPUT" | sed -n '2p')
+          VERSION=$(python -c "import tomllib; print(tomllib.load(open('packages/syft-datasets/pyproject.toml','rb'))['project']['version'])")
           echo "VERSION=$VERSION" >> $GITHUB_ENV
-          echo "MODIFIED=$MODIFIED" >> $GITHUB_ENV
-          echo "Bumped syft-dataset to $VERSION (modified: $MODIFIED)"
+          echo "Releasing syft-dataset $VERSION"
+
+      # Artifacts live inside the package, so they must be committed before the
+      # build. Re-running the export writes nothing when they already exist.
+      - name: Freeze release artifacts
+        run: |
+          uv run python packages/syft-datasets/scripts/export_release_artifact.py
+          git add packages/syft-datasets/src/syft_datasets/migrations/history
+          git diff --cached --quiet || \
+            git commit -m "Freeze syft-dataset v${{ env.VERSION }} release artifacts"
 
       - name: Build package
         working-directory: packages/syft-datasets
@@ -65,9 +73,14 @@ jobs:
           TWINE_PASSWORD: ${{ secrets.PYPI_PASS_SYFT_DATASET }}
         run: uvx twine upload --verbose dist/*
 
-      - name: Commit and tag
+      # The tag must name the published version, so it is created before the bump.
+      - name: Tag the release, then bump for the next one
         run: |
-          git add ${{ env.MODIFIED }}
-          git commit -m "Release syft-dataset v${{ env.VERSION }}"
           git tag "syft-dataset/v${{ env.VERSION }}"
+          pip install packaging
+          OUTPUT=$(python scripts/bump_version.py syft-dataset ${{ inputs.bump_type }} --dependents published)
+          NEXT=$(echo "$OUTPUT" | sed -n '1p')
+          MODIFIED=$(echo "$OUTPUT" | sed -n '2p')
+          git add $MODIFIED
+          git commit -m "Bump syft-dataset to $NEXT for the next release"
           git push origin --follow-tags

.github/workflows/cd-syft-job.yml

@@ -43,16 +43,24 @@ jobs:
           git config user.name "github-actions[bot]"
           git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
 
-      - name: Bump version
+      # The branch already holds the version to release. The bump happens after
+      # the publish, so the version on the branch always names an unreleased
+      # version while people develop.
+      - name: Read the version to release
         run: |
           git pull
-          pip install packaging
-          OUTPUT=$(python scripts/bump_version.py syft-job ${{ inputs.bump_type }})
-          VERSION=$(echo "$OUTPUT" | sed -n '1p')
-          MODIFIED=$(echo "$OUTPUT" | sed -n '2p')
+          VERSION=$(python -c "import tomllib; print(tomllib.load(open('packages/syft-job/pyproject.toml','rb'))['project']['version'])")
           echo "VERSION=$VERSION" >> $GITHUB_ENV
-          echo "MODIFIED=$MODIFIED" >> $GITHUB_ENV
-          echo "Bumped syft-job to $VERSION (modified: $MODIFIED)"
+          echo "Releasing syft-job $VERSION"
+
+      # Artifacts live inside the package, so they must be committed before the
+      # build. Re-running the export writes nothing when they already exist.
+      - name: Freeze release artifacts
+        run: |
+          uv run python packages/syft-job/scripts/export_release_artifact.py
+          git add packages/syft-job/src/syft_job/migrations/history
+          git diff --cached --quiet || \
+            git commit -m "Freeze syft-job v${{ env.VERSION }} release artifacts"
 
       - name: Build package
         working-directory: packages/syft-job
@@ -65,9 +73,14 @@ jobs:
           TWINE_PASSWORD: ${{ secrets.PYPI_PASS_SYFT_JOB }}
         run: uvx twine upload --verbose dist/*
 
-      - name: Commit and tag
+      # The tag must name the published version, so it is created before the bump.
+      - name: Tag the release, then bump for the next one
         run: |
-          git add ${{ env.MODIFIED }}
-          git commit -m "Release syft-job v${{ env.VERSION }}"
           git tag "syft-job/v${{ env.VERSION }}"
+          pip install packaging
+          OUTPUT=$(python scripts/bump_version.py syft-job ${{ inputs.bump_type }} --dependents published)
+          NEXT=$(echo "$OUTPUT" | sed -n '1p')
+          MODIFIED=$(echo "$OUTPUT" | sed -n '2p')
+          git add $MODIFIED
+          git commit -m "Bump syft-job to $NEXT for the next release"
           git push origin --follow-tags

.github/workflows/cd-syft-permissions.yml

@@ -43,16 +43,15 @@ jobs:
           git config user.name "github-actions[bot]"
           git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
 
-      - name: Bump version
+      # The branch already holds the version to release. The bump happens after
+      # the publish, so the version on the branch always names an unreleased
+      # version while people develop.
+      - name: Read the version to release
         run: |
           git pull
-          pip install packaging
-          OUTPUT=$(python scripts/bump_version.py syft-permissions ${{ inputs.bump_type }})
-          VERSION=$(echo "$OUTPUT" | sed -n '1p')
-          MODIFIED=$(echo "$OUTPUT" | sed -n '2p')
+          VERSION=$(python -c "import tomllib; print(tomllib.load(open('packages/syft-permissions/pyproject.toml','rb'))['project']['version'])")
           echo "VERSION=$VERSION" >> $GITHUB_ENV
-          echo "MODIFIED=$MODIFIED" >> $GITHUB_ENV
-          echo "Bumped syft-permissions to $VERSION (modified: $MODIFIED)"
+          echo "Releasing syft-permissions $VERSION"
 
       - name: Build package
         working-directory: packages/syft-permissions
@@ -65,9 +64,14 @@ jobs:
           TWINE_PASSWORD: ${{ secrets.PYPI_PASS_SYFT_PERMISSIONS }}
         run: uvx twine upload --verbose dist/*
 
-      - name: Commit and tag
+      # The tag must name the published version, so it is created before the bump.
+      - name: Tag the release, then bump for the next one
         run: |
-          git add ${{ env.MODIFIED }}
-          git commit -m "Release syft-permissions v${{ env.VERSION }}"
           git tag "syft-permissions/v${{ env.VERSION }}"
+          pip install packaging
+          OUTPUT=$(python scripts/bump_version.py syft-permissions ${{ inputs.bump_type }} --dependents published)
+          NEXT=$(echo "$OUTPUT" | sed -n '1p')
+          MODIFIED=$(echo "$OUTPUT" | sed -n '2p')
+          git add $MODIFIED
+          git commit -m "Bump syft-permissions to $NEXT for the next release"
           git push origin --follow-tags

.github/workflows/cd-syft-perms.yml

@@ -43,16 +43,15 @@ jobs:
           git config user.name "github-actions[bot]"
           git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
 
-      - name: Bump version
+      # The branch already holds the version to release. The bump happens after
+      # the publish, so the version on the branch always names an unreleased
+      # version while people develop.
+      - name: Read the version to release
         run: |
           git pull
-          pip install packaging
-          OUTPUT=$(python scripts/bump_version.py syft-perms ${{ inputs.bump_type }})
-          VERSION=$(echo "$OUTPUT" | sed -n '1p')
-          MODIFIED=$(echo "$OUTPUT" | sed -n '2p')
+          VERSION=$(python -c "import tomllib; print(tomllib.load(open('packages/syft-perms/pyproject.toml','rb'))['project']['version'])")
           echo "VERSION=$VERSION" >> $GITHUB_ENV
-          echo "MODIFIED=$MODIFIED" >> $GITHUB_ENV
-          echo "Bumped syft-perms to $VERSION (modified: $MODIFIED)"
+          echo "Releasing syft-perms $VERSION"
 
       - name: Build package
         working-directory: packages/syft-perms
@@ -65,9 +64,14 @@ jobs:
           TWINE_PASSWORD: ${{ secrets.PYPI_PASS_SYFT_PERMS }}
         run: uvx twine upload --verbose dist/*
 
-      - name: Commit and tag
+      # The tag must name the published version, so it is created before the bump.
+      - name: Tag the release, then bump for the next one
         run: |
-          git add ${{ env.MODIFIED }}
-          git commit -m "Release syft-perms v${{ env.VERSION }}"
           git tag "syft-perms/v${{ env.VERSION }}"
+          pip install packaging
+          OUTPUT=$(python scripts/bump_version.py syft-perms ${{ inputs.bump_type }} --dependents published)
+          NEXT=$(echo "$OUTPUT" | sed -n '1p')
+          MODIFIED=$(echo "$OUTPUT" | sed -n '2p')
+          git add $MODIFIED
+          git commit -m "Bump syft-perms to $NEXT for the next release"
           git push origin --follow-tags

.github/workflows/post-release-tests.yml

@@ -62,3 +62,8 @@ jobs:
         run: |
           source .venv/bin/activate
           pytest -n auto ./tests/unit
+
+      - name: Run client migration tests
+        run: |
+          source .venv/bin/activate
+          pytest -n auto ./tests/migrations

.github/workflows/unit-tests.yml

@@ -198,3 +198,6 @@ jobs:
 
       - name: Run migration tests
         run: just test-unit-migration
+
+      - name: Run client migration tests
+        run: just test-client-migrations

Justfile

@@ -10,7 +10,6 @@ _nc := '\033[0m'
 
 alias b := build
 alias p := publish
-alias bp:= bump-and-publish
 # ---------------------------------------------------------------------------------------------------------------------
 
 
@@ -38,6 +37,10 @@ test-unit-migration:
     #!/bin/bash
     uv run pytest -n auto ./packages/syft-migration/tests
 
+test-client-migrations:
+    #!/bin/bash
+    uv run pytest -n auto ./tests/migrations
+
 
 test-unit-enclave:
     #!/bin/bash
@@ -136,12 +139,10 @@ publish: build
     uvx twine upload dist/*
     @echo "{{ _green }}Publish complete!{{ _nc }}"
 
-# Bump version and publish to PyPI
+# Export the frozen release artifacts for the current version
 [group('publish')]
-bump-and-publish part="patch":
-    just bump {{ part }}
-    just publish
-    @echo "{{ _green }}Bump and publish complete!{{ _nc }}"
+export-release-artifacts:
+    uv run python scripts/export_release_artifact.py
 
 # Launch Jupyter Lab
 jupyter:

docs/release.md

@@ -2,16 +2,46 @@
 
 ## Overview
 
-Releases are managed through dedicated release branches. The mono repo release job handles bumping versions and pushing tags for all individual packages automatically.
+Releases are managed through dedicated release branches. The mono repo release job handles publishing, tagging and bumping versions for all individual packages automatically.
+
+## Version order
+
+A release publishes the version that is **already on the branch**. The release then tags that version. After the tag, the release job bumps the version for the next release.
+
+The version on a branch is always a version that is **not yet published**. Therefore one version string always refers to one build.
+
+Do not change a version by hand before a release. The release job makes the bump.
 
 ## Steps
 
-1. **Create a release branch** from `main`, dont include the patch version in the semver, so we can hotfix patches on the same branch (e.g. `release/v0.1`). If you are patching, re-use the branch
+1. **Create a release branch** from `main`, don't include the patch version in the semver, so we can hotfix patches on the same branch (e.g. `release/v0.1`). If you are patching, re-use the branch.
 2. **Run the release workflow.** You can trigger frmo github UI from the Actions tab. In most cases, release the mono repo — this releases all individual packages (`syft-client`, `syft-job`, `syft-dataset`, etc.) in one go. You only need to release individual packages if they are changed, but we are not detecting that automatically currently.
 3. **Integration tests are optional.** You can skip them during the release if needed. Unit tests should still pass.
-4. **Versions are bumped **before releasing to pypi** and pushed automatically** by the release process — no manual version edits required.
+4. **The release job publishes, tags, and then bumps the version.** No manual version edit is necessary.
 5. Merge the release branch back into `main` to ensure all version bumps and hotfixes are carried forward.
 
+## Release artifacts
+
+`syft-client`, `syft-job`, and `syft-dataset` each write a release artifact. The artifact records the object versions of that release. It also records the exact schema of each object version.
+
+The drift check compares the current models against these files. If an artifact is absent, the drift check has nothing to compare for that version.
+
+The artifacts are inside the package, so the release job runs the export before the build:
+
+```
+uv run python scripts/export_release_artifact.py                        # syft-client
+uv run python packages/syft-job/scripts/export_release_artifact.py      # syft-job
+uv run python packages/syft-datasets/scripts/export_release_artifact.py # syft-dataset
+```
+
+A developer can also run an export in a pull request. The version on the branch is the version that the next release publishes. The artifact is therefore available for review before the release.
+
+An artifact is permanent. If an artifact for a version exists, a second export writes nothing and reports success.
+
+An export stops with an error if the protocol changed but the protocol version constant did not change. The error message gives the name of the constant to bump.
+
+The drift check has one known limit. A new protocol generation adds object versions, and no artifact freezes those versions until the release of that generation. The drift check therefore cannot see a change to them. Frequent releases keep this period short.
+
 ## Hotfixes
 
 If a fix is needed after cutting the release branch, apply the hotfix directly to the release branch and re-release from there.