From 51d3caaa72e16b94f9f82ab3990c46f8f03eac9d Mon Sep 17 00:00:00 2001
From: James Dempsey <dempsey@tapas-software.net>
Date: Wed, 24 Jun 2026 08:37:59 -0700
Subject: [PATCH] Add proposal validation workflow and documentation

---
 .github/workflows/proposal_validation.yml | 54 +++++++++++++++++++++++
 README.md                                 | 32 ++++++++++++++
 2 files changed, 86 insertions(+)
 create mode 100644 .github/workflows/proposal_validation.yml

diff --git a/.github/workflows/proposal_validation.yml b/.github/workflows/proposal_validation.yml
new file mode 100644
index 00000000..0eb610da
--- /dev/null
+++ b/.github/workflows/proposal_validation.yml
@@ -0,0 +1,54 @@
+name: Proposal Validation
+
+on:
+  workflow_call:
+    inputs:
+      project:
+        type: string
+        description: "Name of project supported by swift-evolution-metadata-extractor tool"
+        default: swift
+
+jobs:
+  run-swift-evolution-metadata-extractor:
+    name: Validate proposals with swift-evolution-metadata-extractor
+    runs-on: ubuntu-latest
+    container:
+      image: "swift:6.2-noble"
+    timeout-minutes: 10
+    steps:
+      - name: Checkout swiftlang/swift-evolution-metadata-extractor (main)
+        uses: actions/checkout@v6
+        with:
+          repository: swiftlang/swift-evolution-metadata-extractor
+          ref: main
+          path: seme
+
+      - name: Create cache key
+        id: cache-key
+        run: echo "key=seme-$(git -C seme rev-parse HEAD)" >> $GITHUB_OUTPUT
+
+      - name: Restore cache
+        uses: actions/cache/restore@v5
+        id: restore-cache
+        with:
+          path: ${{ github.workspace }}/swift-evolution-metadata-extractor
+          key: ${{ steps.cache-key.outputs.key }}
+
+      - name: Build swift-evolution-metadata-extractor (release)
+        if: steps.restore-cache.outputs.cache-hit != 'true'
+        run: |
+          swift --version
+          swift build -c release --very-verbose
+          cp .build/release/swift-evolution-metadata-extractor $GITHUB_WORKSPACE/swift-evolution-metadata-extractor
+        working-directory: seme
+
+      - name: Save to cache
+        if: steps.restore-cache.outputs.cache-hit != 'true'
+        id: save-to-cache
+        uses: actions/cache/save@v5
+        with:
+          path: ${{ github.workspace }}/swift-evolution-metadata-extractor
+          key: ${{ steps.cache-key.outputs.key }}
+
+      - name: Validate proposals
+        run: $GITHUB_WORKSPACE/swift-evolution-metadata-extractor validate --pull-request ${{ github.event.number }}
diff --git a/README.md b/README.md
index 2bb75bc2..de2f40de 100644
--- a/README.md
+++ b/README.md
@@ -94,6 +94,38 @@ Linked PR: swiftlang/swift-syntax#2859
 
 Enabling cross-PR testing will add about 10s to PR testing time.
 
+### Evolution Proposal Validation
+
+The proposal validation workflow validates added and changed proposals in a pull request to check for formatting and content errors that will cause metadata extraction to fail or be incomplete.
+
+To accomplish this, the workflow builds the [swift-evolution-metadata-extractor](https://github.com/swiftlang/swift-evolution-metadata-extractor) tool and runs its `validate` command.  To minimize validation times, the built tool is cached and only rebuilt when the tool has changed.
+
+To use the proposal validation workflow, add a workflow to the repository that contains the directory of proposals.  The calling workflow specifies project-specific details such as the directory where the proposals are located.  It is only run if a pull request contains changes in the specified directory.
+
+> [!NOTE]
+> The extraction tool currently only supports the evolution proposals of the Swift project at swiftlang/swift-evolution/proposals. The tool and workflow has been designed to be extended to support additional projects in the future.
+
+An example workflow for Swift Testing which uses a subfolder in the swift-evolution repository:
+
+```yaml
+name: Validate proposals with swift-evolution-metadata-extractor
+
+on:
+  pull_request:
+    types: [opened, reopened, synchronize]
+    branches:
+      - 'main'
+    paths:
+      - 'proposals/testing/*'
+
+jobs:
+  validate:
+    name: Validate Proposals
+    uses: swiftlang/github-workflows/.github/workflows/proposal_validation.yml@main
+    with:
+      project: "testing"
+```
+
 ## Running workflows locally
 
 You can run the Github Actions workflows locally using