From d1a0dbcac3cc5b07e4c4d4d215dd1ef0cfa8d5ae Mon Sep 17 00:00:00 2001
From: Julie Muzina <julie.muzina@canonical.com>
Date: Tue, 18 Jun 2024 10:18:34 -0400
Subject: [PATCH] Add more docs to Percy workflows; add Percy testing section
 to pull requests guide

---
 .github/workflows/percy-prepare.yml          |  2 ++
 .github/workflows/pr-percy-prepare-label.yml |  5 ++--
 .github/workflows/pr-percy-prepare-push.yml  |  5 ++--
 .github/workflows/pr-percy-snapshots.yml     |  1 +
 guides/pull-requests.md                      | 28 ++++++++++++++++++++
 5 files changed, 37 insertions(+), 4 deletions(-)

diff --git a/.github/workflows/percy-prepare.yml b/.github/workflows/percy-prepare.yml
index 4ebd67d37..7b72ffe37 100644
--- a/.github/workflows/percy-prepare.yml
+++ b/.github/workflows/percy-prepare.yml
@@ -1,3 +1,5 @@
+# This workflow is triggered by the `pr-percy-prepare` workflows.
+# It checks out the SCSS/example markup changes and uploads them to Github as an artifact.
 name: "Prepare Percy build"
 
 on:
diff --git a/.github/workflows/pr-percy-prepare-label.yml b/.github/workflows/pr-percy-prepare-label.yml
index 3a81b8a45..7f6a87d5d 100644
--- a/.github/workflows/pr-percy-prepare-label.yml
+++ b/.github/workflows/pr-percy-prepare-label.yml
@@ -8,7 +8,6 @@ on:
     types:
         # workflow runs after a label is added to the PR, or when a commit is added to a PR with the Percy label
       - labeled
-      - ready_for_review
       - synchronize
 
 jobs:
@@ -19,4 +18,6 @@ jobs:
     with:
       pr_number: ${{ github.event.number }}
       repository: ${{ github.repository }}
-      commitsh: ${{ github.event.pull_request.head.sha }}
\ No newline at end of file
+      commitsh: ${{ github.event.pull_request.head.sha }}
+
+# Completion should trigger `pr-percy-snapshots` workflow.
diff --git a/.github/workflows/pr-percy-prepare-push.yml b/.github/workflows/pr-percy-prepare-push.yml
index 9c0ecdf60..0fc6f5f73 100644
--- a/.github/workflows/pr-percy-prepare-push.yml
+++ b/.github/workflows/pr-percy-prepare-push.yml
@@ -10,7 +10,6 @@ on:
       - "scss/**"
     types:
       - opened
-      - ready_for_review
       - synchronize
 
 jobs:
@@ -23,4 +22,6 @@ jobs:
     with:
       pr_number: ${{ github.event.number }}
       repository: ${{ github.repository }}
-      commitsh: ${{ github.event.pull_request.head.sha }}
\ No newline at end of file
+      commitsh: ${{ github.event.pull_request.head.sha }}
+
+# Completion should trigger `pr-percy-snapshots` workflow.
diff --git a/.github/workflows/pr-percy-snapshots.yml b/.github/workflows/pr-percy-snapshots.yml
index 446993362..6cadda20e 100644
--- a/.github/workflows/pr-percy-snapshots.yml
+++ b/.github/workflows/pr-percy-snapshots.yml
@@ -1,3 +1,4 @@
+# This workflow listens for completion of the `pr-percy-prepare` workflows, picks up their outputs, and performs Percy testing.
 name: "Percy screenshots"
 
 on:
diff --git a/guides/pull-requests.md b/guides/pull-requests.md
index 449438e02..a7552bbe5 100644
--- a/guides/pull-requests.md
+++ b/guides/pull-requests.md
@@ -78,6 +78,34 @@ apply the relevant `-1` Labels.
 
 ### Submitting & merging a PR
 
+#### Percy visual testing
+
+We use [Percy](https://percy.io) for visual testing. Percy tests are run against pull requests to
+ensure that PRs to not introduce visual regressions. Your PR will be tested by Percy if it meets the following conditions:
+
+- PR is against the `main` branch
+- One of the following is true:
+  - PR passes Percy selectivity filters
+    - PR changes files in the `scss/` or `templates/docs/examples/` directories
+    - PR is not a draft
+  - PR is labeled with "Review: Percy needed"
+
+To ensure optimal Percy usage, we suggest the following PR flow:
+
+1. Open the PR (against `main`) in such a way that it causes an initial Percy test to run.
+   - If your PR makes changes to files in the `scss/` or `templates/docs/examples/` directories, it will be automatically
+     tested as long as it is not marked as a draft.
+   - Applying the "Review: Percy needed" label to the PR ensures that it is always tested.
+2. Review the initial [Percy build](https://percy.io/bb49709b/vanilla-framework).
+3. If there are additional changes needed to the PR through the review process, you can remove the "Review: Percy needed"
+   label and mark the PR as a draft to prevent additional Percy tests from running.
+4. Once the PR is ready for final review, remove the draft status and reapply the "Review: Percy needed" label to trigger
+   a final Percy test.
+5. If the Percy test passes, apply "Review: Percy +1" to indicate that the PR has passed Percy testing.
+6. If all other reviews have been completed, the PR is ready to be merged.
+
+#### Merging a PR
+
 After the necessary review steps have been completed and the PR is ready to be
 merged, the creator of the PR should merge it themself. The type of merge to use
 should be decided using the following logic: