From aaacb07ed9a8388929475dda33f881bc402d73dc Mon Sep 17 00:00:00 2001
From: jrfnl <jrfnl@users.noreply.github.com>
Date: Sun, 15 Jun 2025 12:32:25 +0200
Subject: [PATCH] GH Actions: add a workflow to automatically deploy the wiki

This commit introduces a workflow, which will:
* Automatically deploy the wiki files to the [PHP_CodeSniffer repo wiki](https://github.com/PHPCSStandards/PHP_CodeSniffer/wiki) on every push to the `main` branch.
* Will do a dry-run, without actually deploying, whenever a PR is created which would update the wiki files.

This way, the wiki is opened up to contributions via pull requests and is no longer limited to only edits made by committers.

A prominent warning is automatically added as a (hidden) comment at the top of each wiki file to warn committers not to edit the wiki file in the GitHub wiki interface.
Any edits made via the GitHub wiki interface or by directly pushing to the wiki repository, will be lost and overwritten via this workflow the next time a change is pushed to the `main` branch of this repo.

This commit also adds a `_Footer.md` file, which will automatically be displayed at the bottom of each wiki page to point out that the wiki is editable via PRs to this repo.

Notes:
* The files are copied to a `_wiki` directory - which is `.gitignore`d - before pre-processing to reduce the risk of the source files being accidentally updated (and committed), which would undo the automation.
* Commits for "push" events to the `main` branch will get the same commit message for the wiki as the _last_ commit on the `main` branch.
    For that reason, merge commits are not allowed in this repo and PRs with only one commit are strongly preferred.
* Dry-run commits for PR events and commits triggered by other events, will get a simplified message referencing the sha of the last commit.
* If the net effect of a commit results in no changes to the wiki files (CI changes and such), no commit will be made to the wiki.
* The workflow is set up to fail if GitHub has an outage for git operations.
    That should protect the wiki from going down by a broken/partial commit and allows for retriggering a deploy once the outage has passed by re-running the failed build.

Future scope (upcoming):
* Automate generation of the Table of Contents for wiki pages.
* Automate re-generation of output examples used in the wiki pages.

Refs:
* https://github.com/Andrew-Chen-Wang/github-wiki-action
* https://github.com/crazy-max/ghaction-github-status
---
 .github/workflows/publish-wiki.yml | 71 ++++++++++++++++++++++++++++++
 .gitignore                         |  1 +
 wiki/_Footer.md                    |  3 ++
 3 files changed, 75 insertions(+)
 create mode 100644 .github/workflows/publish-wiki.yml
 create mode 100644 .gitignore
 create mode 100644 wiki/_Footer.md

diff --git a/.github/workflows/publish-wiki.yml b/.github/workflows/publish-wiki.yml
new file mode 100644
index 0000000..0998cc8
--- /dev/null
+++ b/.github/workflows/publish-wiki.yml
@@ -0,0 +1,71 @@
+name: Publish wiki
+on:
+  push:
+    branches:
+      - 'main'
+    paths:
+      - wiki/**
+      - .github/workflows/publish-wiki.yml
+  # Do a dry-run (check, no deploy) for PRs.
+  pull_request:
+    paths:
+      - wiki/**
+      - .github/workflows/publish-wiki.yml
+  # Allow running this workflow manually from the Actions tab.
+  workflow_dispatch:
+  # Allow this workflow to be triggered from outside.
+
+# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
+# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
+concurrency:
+  group: "publish-wiki"
+  cancel-in-progress: false
+
+jobs:
+  publish-wiki:
+    name: "Publish Wiki"
+    if: github.repository == 'PHPCSStandards/PHP_CodeSniffer-documentation'
+
+    runs-on: ubuntu-latest
+
+    permissions:
+      # Needed for the commit to the wiki.
+      contents: write
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Copy wiki files to temporary location
+        shell: bash
+        run: cp -v -a wiki _wiki
+
+      - name: Preface markdown files with warning not to edit in place
+        shell: bash
+        # yamllint disable rule:line-length
+        # shellcheck disable=SC2016
+        run: >
+          find ./_wiki/ -name "*.md*"
+          -exec sed -i
+          '1i\<!--\nWARNING: DO NOT EDIT THIS FILE IN THE WIKI.\nThis wiki is updated from the https://github.com/PHPCSStandards/PHP_CodeSniffer-documentation repository.\nSubmit a PR to that repository updating the relevant file in the /wiki/ subdirectory instead.\n-->\n' {} \;
+          # yamllint enable rule:line-length
+
+      - name: Check GitHub Git Operations status
+        uses: crazy-max/ghaction-github-status@v4
+        with:
+          git_threshold: partial_outage
+
+      - name: Deploy to wiki
+        uses: Andrew-Chen-Wang/github-wiki-action@v5.0.1
+        env:
+          COMMIT_MSG: ${{ github.event.head_commit.message }}
+          DEFAULT_COMMIT_MSG: "Update wiki ${{ github.sha }}"
+        with:
+          strategy: 'clone'
+          path: '_wiki/'
+          commit-message: ${{ env.COMMIT_MSG != '' && env.COMMIT_MSG || env.DEFAULT_COMMIT_MSG }}
+          repository: PHPCSStandards/PHP_CodeSniffer
+          token: ${{ secrets.PHPCS_PUSH_TO_WIKI_TOKEN }}
+          dry-run: ${{ github.event_name == 'pull_request' }}
+          disable-empty-commits: true
+          preprocess: false
diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..1388517
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1 @@
+_wiki/
diff --git a/wiki/_Footer.md b/wiki/_Footer.md
new file mode 100644
index 0000000..9eaf6ff
--- /dev/null
+++ b/wiki/_Footer.md
@@ -0,0 +1,3 @@
+_Found a mistake ? Think this documentation can be improved ?_
+
+Contributions to this wiki are welcome! Submit a pull request to the [Documentation repository](https://github.com/PHPCSStandards/PHP_CodeSniffer-documentation) to propose your changes.