docs: update workflows to use contractual-dev/action and document release automation

Author: omermorad

.github/workflows/release.yml

@@ -1,28 +1,25 @@
-name: Version Contracts
+name: Release Contracts
 
 on:
   push:
     branches:
       - main
-    paths:
-      - '.contractual/changesets/**'
-      - '!.contractual/changesets/.gitkeep'
 
 permissions:
   contents: write
   pull-requests: write
 
 jobs:
-  version:
+  release:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout code
         uses: actions/checkout@v4
         with:
           fetch-depth: 0
 
-      - name: Version Contracts
-        id: version
+      - name: Release Contracts
+        id: release
         uses: contractual-dev/action@v1
         with:
           mode: release
@@ -31,9 +28,19 @@ jobs:
           tag-prefix: 'contract'
           attach-specs: 'true'
 
-      - name: Summary
-        if: steps.version.outputs.version-pr-url
+      - name: Release Summary
+        if: always()
         run: |
-          echo "📦 Version PR: ${{ steps.version.outputs.version-pr-url }}"
-          echo "🏷️  Tags created: ${{ steps.version.outputs.created-tags }}"
-          echo "🚀 Releases: ${{ steps.version.outputs.release-urls }}"
+          echo "### Release Summary" >> $GITHUB_STEP_SUMMARY
+          if [ -n "${{ steps.release.outputs.version-pr-url }}" ]; then
+            echo "📦 Version PR created: ${{ steps.release.outputs.version-pr-url }}" >> $GITHUB_STEP_SUMMARY
+          fi
+          if [ -n "${{ steps.release.outputs.created-tags }}" ]; then
+            echo "🏷️  Tags: ${{ steps.release.outputs.created-tags }}" >> $GITHUB_STEP_SUMMARY
+          fi
+          if [ -n "${{ steps.release.outputs.release-urls }}" ]; then
+            echo "🚀 Releases: ${{ steps.release.outputs.release-urls }}" >> $GITHUB_STEP_SUMMARY
+          fi
+          if [ -n "${{ steps.release.outputs.bumped-versions }}" ]; then
+            echo "📈 Bumped: ${{ steps.release.outputs.bumped-versions }}" >> $GITHUB_STEP_SUMMARY
+          fi

README.md

@@ -102,15 +102,31 @@ When you open a PR with spec changes:
 
 If breaking changes are detected or no changeset exists, the check fails.
 
-### Release Workflow
-
-When a PR with changesets is merged to `main`:
-
-1. **Consume Changesets**: Reads all pending changesets
-2. **Bump Versions**: Applies semantic version bumps
-3. **Update Changelog**: Appends changes to `CHANGELOG.md`
-4. **Snapshot Spec**: Copies current spec to `.contractual/snapshots/`
-5. **Commit & Push**: Commits changes back to main
+### Release Workflow (Automated)
+
+The release workflow uses the **Changesets pattern** with two phases:
+
+#### **Phase 1: Version PR Creation**
+When changesets are merged to `main`:
+
+1. **Detect Changesets**: Checks if changesets exist in `.contractual/changesets/`
+2. **Create Version PR**: Opens/updates a PR named "Version Contracts" that:
+   - Runs `contractual version` to bump versions
+   - Updates `CHANGELOG.md` with changes
+   - Updates snapshots in `.contractual/snapshots/`
+   - Removes consumed changesets
+3. **PR Review**: Team reviews the version bumps before release
+
+#### **Phase 2: Release Creation**
+When the Version PR is merged to `main`:
+
+1. **Detect Version Bump**: Checks if `versions.json` changed
+2. **Create Git Tags**: Tags like `petstore@1.1.0` for each versioned contract
+3. **Create GitHub Releases**: One release per contract with:
+   - Changelog excerpt for that contract
+   - Attached OpenAPI spec file from snapshots
+   - Release notes with breaking change warnings
+4. **Publish**: (Optional, Phase 3) Publish to package registries
 
 ---