[docs] Document branch protection workflow (#61)

docs/advanced/branch-protection-and-bot-commits.rst

@@ -0,0 +1,117 @@
+Branch Protection and Bot Commits
+=================================
+
+Fast Forward repositories keep generated documentation out of protected
+branches until the related pull request is merged. This keeps ``main`` stable,
+lets maintainers review generated output before it becomes canonical, and
+avoids requiring automation to bypass branch protection for normal preview
+updates.
+
+The model has two publishing lanes:
+
+- pull requests publish isolated previews;
+- merges into ``main`` publish the final wiki and reports.
+
+Wiki Preview Lifecycle
+----------------------
+
+The wiki workflow writes generated Markdown to the GitHub wiki repository, but
+it does not publish pull request content directly to the wiki ``master`` branch.
+Instead, each pull request receives a dedicated wiki branch.
+
+For pull request ``123`` the workflow:
+
+1. runs ``composer dev-tools wiki -- --target=.github/wiki``;
+2. commits the generated wiki content to the wiki branch ``pr-123``;
+3. updates the parent repository submodule pointer at ``.github/wiki``;
+4. commits that pointer update back to the pull request branch.
+
+The parent repository commit is important because reviewers can see exactly
+which generated wiki revision belongs to the pull request. The bot commit SHOULD
+stay on the pull request branch because protected ``main`` branches usually
+reject direct commits.
+
+After the pull request is merged into ``main``, the publish job copies the
+content from the wiki preview branch, such as ``pr-123``, to the wiki
+``master`` branch. That makes the reviewed wiki content live only after the
+source code merge is complete.
+
+Reports Preview Lifecycle
+-------------------------
+
+Reports use the same review-before-publish idea, but the output is served from
+GitHub Pages instead of the wiki repository.
+
+On pull requests, the reports workflow:
+
+- generates docs, coverage, and report assets from the pull request code;
+- publishes them under ``previews/pr-<number>/`` in the Pages branch;
+- comments on the pull request with preview links when possible;
+- keeps workflow artifacts available as a fallback when Pages publishing or the
+  comment update is unavailable.
+
+On ``main``, the reports workflow publishes the final site at the root of the
+Pages branch. Pull request previews use PR-specific directories, so multiple
+open pull requests can have independent previews without overwriting each other.
+
+When a pull request is closed, the workflow SHOULD remove its preview directory.
+This prevents stale documentation and coverage reports from looking like active
+review artifacts.
+
+Branch Protection Interactions
+------------------------------
+
+Protected branches usually block direct pushes, require status checks, and may
+require signed commits or linear history. The preview workflows are designed to
+respect those rules:
+
+- bot commits update the pull request branch, not ``main``;
+- final wiki publication runs after the merge into ``main``;
+- final reports publication runs from the already-accepted ``main`` revision;
+- preview branches such as ``pr-123`` are temporary review targets.
+
+If a repository restricts bot pushes to pull request branches, maintainers
+should either allow the workflow token to update PR branches or require authors
+to refresh generated pointers manually. The preferred path is to allow bot
+updates on PR branches while keeping ``main`` protected.
+
+At a high level, the workflows need permission to read repository contents,
+write generated preview commits, update pull request comments, and publish Pages
+content. Keep those permissions scoped to the workflow jobs that actually need
+them.
+
+Resolving ``.github/wiki`` Pointer Conflicts
+--------------------------------------------
+
+Submodule pointer conflicts happen when ``main`` and the pull request point to
+different generated wiki commits. Resolve them by rebasing the pull request and
+choosing the preview wiki commit that belongs to the pull request.
+
+For pull request ``123``:
+
+.. code-block:: bash
+
+    git fetch origin main
+    git rebase origin/main
+    git -C .github/wiki fetch origin master pr-123
+    git -C .github/wiki switch --detach origin/pr-123
+    git add .github/wiki
+    git rebase --continue
+    git push --force-with-lease
+
+If the conflict appears after the preview job has already produced a newer bot
+commit, prefer the latest ``pr-123`` wiki commit. If the wiki branch no longer
+exists because the pull request was closed or merged, rerun the wiki workflow or
+regenerate the wiki locally before updating the pointer.
+
+Operational Checklist
+---------------------
+
+- Keep source changes and generated pointer updates in the same pull request.
+- Review PR preview links before merging documentation-heavy changes.
+- Merge only through the protected ``main`` flow.
+- Let the post-merge wiki job publish to ``master``.
+- Let closed pull requests clean up their report preview directories.
+
+See :doc:`consumer-automation` for how reusable workflows and consumer stubs fit
+into this model, and :doc:`../usage/github-actions` for the workflow summary.

docs/advanced/consumer-automation.rst

@@ -36,16 +36,23 @@ How GitHub Pages Publishing Works
 ---------------------------------
 
 - ``.github/workflows/reports.yml`` runs ``composer dev-tools reports``.
-- The workflow uploads ``public/`` as the Pages artifact.
-- On the ``main`` branch, GitHub Pages serves the generated site.
+- Pull requests publish previews under ``previews/pr-<number>/``.
+- On the ``main`` branch, GitHub Pages serves the generated site from the root
+  of the Pages branch.
 
 How Wiki Publishing Works
 -------------------------
 
 - ``.github/workflows/wiki.yml`` runs
   ``composer dev-tools wiki -- --target=.github/wiki``.
-- The workflow commits the wiki submodule contents.
-- The parent repository then commits the updated submodule pointer.
+- Pull requests publish generated wiki content to branches such as
+  ``pr-123``.
+- The parent repository then commits the updated submodule pointer to the pull
+  request branch.
+- After merge, the preview content is promoted to the wiki ``master`` branch.
+
+See :doc:`branch-protection-and-bot-commits` for the branch protection model,
+bot commit behavior, and ``.github/wiki`` conflict resolution steps.
 
 Producer Impact
 ---------------

docs/advanced/index.rst

@@ -9,5 +9,6 @@ custom Rector and PHPDoc behavior.
    :maxdepth: 1
 
    consumer-automation
+   branch-protection-and-bot-commits
    phpunit-extension
    rector-and-phpdoc

docs/usage/github-actions.rst

@@ -18,6 +18,9 @@ Example of an inherited workflow:
 
 This approach ensures that all libraries in the ecosystem benefit from infrastructure updates without requiring manual changes to every repository.
 
+For the protected-branch-safe preview and publish model, see
+:doc:`../advanced/branch-protection-and-bot-commits`.
+
 Fast Forward Reports
 --------------------
 
@@ -48,6 +51,8 @@ The ``wiki.yml`` workflow synchronizes the documentation generated by the ``dev-
 
 .. note::
    See :doc:`../configuration/repository-setup` for mandatory initial setup required for the Wiki workflow to function.
+   See :doc:`../advanced/branch-protection-and-bot-commits` for branch
+   protection, bot commit, and submodule pointer conflict guidance.
 
 Fast Forward Tests
 ------------------