Refactor GitHub Actions workflows for cleaner versioning and releases

Publish workflow:
- Add version checking to skip publishing when unchanged
- Use PAT_TOKEN to enable cascading workflow triggers
- Create clean semver tags (v0.5.1) without magg/ prefix
- Create movable 2-digit tags (v0.5) for minor version tracking
- Rename magg/latest to latest-publish for clarity
- Only publish to PyPI when version changes

Docker workflow:
- Trigger on main/beta pushes and v*.*.* semver tags
- Fix metadata tags to handle 3-digit versions properly
- Support both versioned and branch-based image tags
- Remove 4-digit version pattern that wasn't semver compliant

Manual publish workflow:
- Restrict to pre/post/dev releases only (no regular versions)
- Add validation script using JSON output and importlib.metadata
- Auto-create GitHub releases for post-releases by default
- Update latest-publish tag for post-releases of current version
- Include proper changelog in GitHub releases
- Make PyPI publish the final step after all validations

Add packaging dependency for version validation in manual releases.

This creates a cleaner separation between automatic releases (regular
versions on main) and manual releases (pre/post/dev versions), while
maintaining proper version tracking and Docker image tagging.

Signed-off-by: Phillip Sitbon <[email protected]>

Author: sitbon

.github/workflows/docker-publish.yml

@@ -2,8 +2,8 @@ name: Docker
 
 on:
   push:
-    branches: [ beta ]
-    tags: [ 'magg/v*' ]
+    branches: [ main, beta ]
+    tags: [ 'v*.*.*' ]
   pull_request:
     branches: [ main, beta ]
   workflow_dispatch:
@@ -13,88 +13,167 @@ env:
   IMAGE_NAME: ${{ github.repository }}
 
 jobs:
-  test-dev-container:
+  build-dev-image:
+    name: Build Dev Image
     runs-on: ubuntu-latest
+
     permissions:
       contents: read
-      packages: write
-    
+
     strategy:
       matrix:
-        python-version: ['3.12', '3.13']
+        python-version: [ '3.12', '3.13' ]
       fail-fast: false
-    
+
     steps:
       - name: Checkout
         uses: actions/checkout@v4
-      
+
       - name: Set up Docker Buildx
         uses: docker/setup-buildx-action@v3
-      
+
       - name: Log in to Container Registry
         uses: docker/login-action@v3
         with:
           registry: ${{ env.REGISTRY }}
           username: ${{ github.actor }}
           password: ${{ secrets.GITHUB_TOKEN }}
-      
-      - name: Extract metadata
-        id: meta
-        uses: docker/metadata-action@v5
-        with:
-          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
-          tags: |
-            type=ref,event=branch,suffix=-dev-py${{ matrix.python-version }}
-            type=ref,event=pr,suffix=-dev-py${{ matrix.python-version }}
-            type=semver,pattern=v{{major}}.{{minor}}.{{patch}}.{{build}},prefix=,suffix=-dev-py${{ matrix.python-version }}
-            type=raw,value=${{ github.ref_name == 'main' && 'dev' || format('{0}-dev', github.ref_name) }},enable=${{ matrix.python-version == '3.13' && startsWith(github.ref, 'refs/heads/') }}
-      
-      - name: Build dev image
+
+      - name: Build Dev Image
         uses: docker/build-push-action@v6
         with:
           context: .
           file: ./dockerfile
           target: dev
           push: false
-          tags: ${{ steps.meta.outputs.tags }}
+          tags: dev-image:${{ matrix.python-version }}
+          # tags: ${{ steps.meta.outputs.tags }}
           # labels: ${{ steps.meta.outputs.labels }}
           build-args: |
             PYTHON_VERSION=${{ matrix.python-version }}
           cache-from: type=gha
           cache-to: type=gha,mode=max
-          load: true
           provenance: false
           sbom: false
-      
-      - name: Run tests in container
+
+      - name: Save image as tar
         run: |
-          # Use the first tag only (multiple tags break the docker run command)
-          FIRST_TAG=$(echo "${{ steps.meta.outputs.tags }}" | head -n1)
-          docker run --rm \
-            -e MAGG_LOG_LEVEL= \
-            ${FIRST_TAG} \
-            pytest -v
-      
-      - name: Push dev image
-        if: github.event_name != 'pull_request'
-        uses: docker/build-push-action@v6
+          docker save dev-image:${{ matrix.python-version }} -o dev-image-${{ matrix.python-version }}.tar
+
+      - name: Upload image artifact
+        uses: actions/upload-artifact@v4
         with:
-          context: .
-          file: ./dockerfile
-          target: dev
-          push: true
-          tags: ${{ steps.meta.outputs.tags }}
-          # labels: ${{ steps.meta.outputs.labels }}
-          build-args: |
-            PYTHON_VERSION=${{ matrix.python-version }}
-          cache-from: type=gha
-          cache-to: type=gha,mode=max
-          provenance: false
-          sbom: false
+          name: dev-image-${{ matrix.python-version }}
+          path: dev-image-${{ matrix.python-version }}.tar
+
+  test-dev-image:
+    name: Test Dev Container
+    runs-on: ubuntu-latest
+
+    needs: build-dev-image
+    if: ${{ !startsWith(github.ref, 'refs/tags/') }}  # Only run on branches or PRs, not tags
+
+    permissions:
+      contents: read
+    
+    strategy:
+      matrix:
+        python-version: ['3.12', '3.13']
+      fail-fast: false
+    
+    steps:
+      - name: Download image artifact
+        uses: actions/download-artifact@v4
+        with:
+          name: dev-image-${{ matrix.python-version }}
+
+      - name: Load image
+        run: |
+          docker load -i dev-image-${{ matrix.python-version }}.tar
 
-  build-and-push:
-    needs: test-dev-container
+      - name: Run Container Tests
+        run: |
+          docker run --rm -e MAGG_LOG_LEVEL= dev-image:${{ matrix.python-version }} pytest -v
+
+  push-dev-image:
+    name: Push Dev Images
     runs-on: ubuntu-latest
+
+    needs: [build-dev-image, test-dev-image]
+
+    permissions:
+      contents: read
+      packages: write
+
+    strategy:
+      matrix:
+        python-version: ['3.12', '3.13']
+      fail-fast: false
+
+    steps:
+      - name: Download image artifact
+        uses: actions/download-artifact@v4
+        with:
+          name: dev-image-${{ matrix.python-version }}
+
+      - name: Load image
+        run: |
+          docker load -i dev-image-${{ matrix.python-version }}.tar
+
+      - name: Log in to registry
+        uses: docker/login-action@v3
+        with:
+          registry: ${{ env.REGISTRY }}
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Extract Metadata
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
+          tags: |
+            # pr-NN-dev-py3.XX or pr-NN-dev for 3.13
+            type=ref,event=pr,suffix=-dev-py${{ matrix.python-version }}
+            type=ref,event=pr,suffix=-dev,enable=${{ matrix.python-version == '3.13' }}
+
+            # branch-dev-py3.XX
+            type=ref,event=branch,suffix=-dev-py${{ matrix.python-version }}
+
+            # dev for main branch, only for 3.13
+            type=raw,value=dev,enable=${{ matrix.python-version == '3.13' && github.ref_name == 'main' }}
+
+            # branch-dev for other branches, only for 3.13
+            type=raw,value=${{ github.ref_name }}-dev,enable=${{ matrix.python-version == '3.13' && github.ref_name != 'main' && startsWith(github.ref, 'refs/heads/') }}
+
+            # This matches v1.2.3 and outputs 1.2.3-dev-py3.XX or 1.2.3-dev for 3.13
+            type=semver,pattern=v{{major}}.{{minor}}.{{patch}},pattern={{major}}.{{minor}}.{{patch}},suffix=-dev-py${{ matrix.python-version }}
+            type=semver,pattern=v{{major}}.{{minor}}.{{patch}},pattern={{major}}.{{minor}}.{{patch}},suffix=-dev,enable=${{ matrix.python-version == '3.13' }}
+
+            # This matches v1.2 and outputs 1.2-dev-py3.XX or 1.2-dev for 3.13
+            type=semver,pattern=v{{major}}.{{minor}},pattern={{major}}.{{minor}},suffix=-dev-py${{ matrix.python-version }}
+            type=semver,pattern=v{{major}}.{{minor}},pattern={{major}}.{{minor}},suffix=-dev,enable=${{ matrix.python-version == '3.13' }}
+
+      - name: Tag image with all tags
+        run: |
+          for TAG in ${{ steps.meta.outputs.tags }}; do
+            docker tag dev-image:${{ matrix.python-version }} $TAG
+          done
+        shell: bash
+
+      - name: Push all tags
+        run: |
+          for TAG in ${{ steps.meta.outputs.tags }}; do
+            docker push $TAG
+          done
+        shell: bash
+
+  build-and-push-image:
+    name: Build and Push Image
+    runs-on: ubuntu-latest
+
+    needs: [build-dev-image, test-dev-image]
+
     permissions:
       contents: read
       packages: write
@@ -121,15 +200,16 @@ jobs:
           username: ${{ github.actor }}
           password: ${{ secrets.GITHUB_TOKEN }}
 
-      - name: Extract metadata
+      - name: Extract Metadata
         id: meta
         uses: docker/metadata-action@v5
         with:
           images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
           tags: |
             type=ref,event=branch,suffix=${{ matrix.suffix }}
             type=ref,event=pr,suffix=${{ matrix.suffix }}
-            type=semver,pattern=v{{major}}.{{minor}}.{{patch}}.{{build}},prefix=,suffix=${{ matrix.suffix }}
+            type=semver,pattern=v{{major}}.{{minor}}.{{patch}},pattern={{major}}.{{minor}}.{{patch}},suffix=${{ matrix.suffix }}
+            type=semver,pattern=v{{major}}.{{minor}}.{{patch}},pattern={{major}}.{{minor}},suffix=${{ matrix.suffix }}
             type=raw,value=latest,enable=${{ github.ref == 'refs/heads/main' && matrix.target == 'pro' }}
       
       - name: Build and push Docker image
@@ -147,11 +227,15 @@ jobs:
           sbom: false
 
   cleanup-untagged:
-    needs: [test-dev-container, build-and-push]
+    name: Cleanup Untagged Images
     runs-on: ubuntu-latest
-    if: github.event_name != 'pull_request'
+
+    needs: [test-dev-image, build-and-push-image]
+    if: ${{ github.event_name != 'pull_request' }}
+
     permissions:
       packages: write
+
     steps:
       - name: Delete untagged images
         uses: actions/delete-package-versions@v5