Skip to content

Commit 4dc0241

Browse files
coisacoisa
authored
Merge branch 'main' into codex/73-release-publishing-docs
2 parents bbffa5a + e02cb55 commit 4dc0241

8 files changed

Lines changed: 284 additions & 5 deletions

‎.github/wiki‎

Submodule wiki updated from 6e2dfcc to b56e5a5

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

Lines changed: 117 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,117 @@
1+
Branch Protection and Bot Commits
2+
=================================
3+
4+
Fast Forward repositories keep generated documentation out of protected
5+
branches until the related pull request is merged. This keeps ``main`` stable,
6+
lets maintainers review generated output before it becomes canonical, and
7+
avoids requiring automation to bypass branch protection for normal preview
8+
updates.
9+
10+
The model has two publishing lanes:
11+
12+
- pull requests publish isolated previews;
13+
- merges into ``main`` publish the final wiki and reports.
14+
15+
Wiki Preview Lifecycle
16+
----------------------
17+
18+
The wiki workflow writes generated Markdown to the GitHub wiki repository, but
19+
it does not publish pull request content directly to the wiki ``master`` branch.
20+
Instead, each pull request receives a dedicated wiki branch.
21+
22+
For pull request ``123`` the workflow:
23+
24+
1. runs ``composer dev-tools wiki -- --target=.github/wiki``;
25+
2. commits the generated wiki content to the wiki branch ``pr-123``;
26+
3. updates the parent repository submodule pointer at ``.github/wiki``;
27+
4. commits that pointer update back to the pull request branch.
28+
29+
The parent repository commit is important because reviewers can see exactly
30+
which generated wiki revision belongs to the pull request. The bot commit SHOULD
31+
stay on the pull request branch because protected ``main`` branches usually
32+
reject direct commits.
33+
34+
After the pull request is merged into ``main``, the publish job copies the
35+
content from the wiki preview branch, such as ``pr-123``, to the wiki
36+
``master`` branch. That makes the reviewed wiki content live only after the
37+
source code merge is complete.
38+
39+
Reports Preview Lifecycle
40+
-------------------------
41+
42+
Reports use the same review-before-publish idea, but the output is served from
43+
GitHub Pages instead of the wiki repository.
44+
45+
On pull requests, the reports workflow:
46+
47+
- generates docs, coverage, and report assets from the pull request code;
48+
- publishes them under ``previews/pr-<number>/`` in the Pages branch;
49+
- comments on the pull request with preview links when possible;
50+
- keeps workflow artifacts available as a fallback when Pages publishing or the
51+
comment update is unavailable.
52+
53+
On ``main``, the reports workflow publishes the final site at the root of the
54+
Pages branch. Pull request previews use PR-specific directories, so multiple
55+
open pull requests can have independent previews without overwriting each other.
56+
57+
When a pull request is closed, the workflow SHOULD remove its preview directory.
58+
This prevents stale documentation and coverage reports from looking like active
59+
review artifacts.
60+
61+
Branch Protection Interactions
62+
------------------------------
63+
64+
Protected branches usually block direct pushes, require status checks, and may
65+
require signed commits or linear history. The preview workflows are designed to
66+
respect those rules:
67+
68+
- bot commits update the pull request branch, not ``main``;
69+
- final wiki publication runs after the merge into ``main``;
70+
- final reports publication runs from the already-accepted ``main`` revision;
71+
- preview branches such as ``pr-123`` are temporary review targets.
72+
73+
If a repository restricts bot pushes to pull request branches, maintainers
74+
should either allow the workflow token to update PR branches or require authors
75+
to refresh generated pointers manually. The preferred path is to allow bot
76+
updates on PR branches while keeping ``main`` protected.
77+
78+
At a high level, the workflows need permission to read repository contents,
79+
write generated preview commits, update pull request comments, and publish Pages
80+
content. Keep those permissions scoped to the workflow jobs that actually need
81+
them.
82+
83+
Resolving ``.github/wiki`` Pointer Conflicts
84+
--------------------------------------------
85+
86+
Submodule pointer conflicts happen when ``main`` and the pull request point to
87+
different generated wiki commits. Resolve them by rebasing the pull request and
88+
choosing the preview wiki commit that belongs to the pull request.
89+
90+
For pull request ``123``:
91+
92+
.. code-block:: bash
93+
94+
git fetch origin main
95+
git rebase origin/main
96+
git -C .github/wiki fetch origin master pr-123
97+
git -C .github/wiki switch --detach origin/pr-123
98+
git add .github/wiki
99+
git rebase --continue
100+
git push --force-with-lease
101+
102+
If the conflict appears after the preview job has already produced a newer bot
103+
commit, prefer the latest ``pr-123`` wiki commit. If the wiki branch no longer
104+
exists because the pull request was closed or merged, rerun the wiki workflow or
105+
regenerate the wiki locally before updating the pointer.
106+
107+
Operational Checklist
108+
---------------------
109+
110+
- Keep source changes and generated pointer updates in the same pull request.
111+
- Review PR preview links before merging documentation-heavy changes.
112+
- Merge only through the protected ``main`` flow.
113+
- Let the post-merge wiki job publish to ``master``.
114+
- Let closed pull requests clean up their report preview directories.
115+
116+
See :doc:`consumer-automation` for how reusable workflows and consumer stubs fit
117+
into this model, and :doc:`../usage/github-actions` for the workflow summary.

‎docs/advanced/consumer-automation.rst‎

Lines changed: 11 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -36,16 +36,23 @@ How GitHub Pages Publishing Works
3636
---------------------------------
3737

3838
- ``.github/workflows/reports.yml`` runs ``composer dev-tools reports``.
39-
- The workflow uploads ``public/`` as the Pages artifact.
40-
- On the ``main`` branch, GitHub Pages serves the generated site.
39+
- Pull requests publish previews under ``previews/pr-<number>/``.
40+
- On the ``main`` branch, GitHub Pages serves the generated site from the root
41+
of the Pages branch.
4142

4243
How Wiki Publishing Works
4344
-------------------------
4445

4546
- ``.github/workflows/wiki.yml`` runs
4647
``composer dev-tools wiki -- --target=.github/wiki``.
47-
- The workflow commits the wiki submodule contents.
48-
- The parent repository then commits the updated submodule pointer.
48+
- Pull requests publish generated wiki content to branches such as
49+
``pr-123``.
50+
- The parent repository then commits the updated submodule pointer to the pull
51+
request branch.
52+
- After merge, the preview content is promoted to the wiki ``master`` branch.
53+
54+
See :doc:`branch-protection-and-bot-commits` for the branch protection model,
55+
bot commit behavior, and ``.github/wiki`` conflict resolution steps.
4956

5057
Producer Impact
5158
---------------

‎docs/advanced/index.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,5 +9,6 @@ custom Rector and PHPDoc behavior.
99
:maxdepth: 1
1010

1111
consumer-automation
12+
branch-protection-and-bot-commits
1213
phpunit-extension
1314
rector-and-phpdoc

‎docs/usage/github-actions.rst‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,9 @@ Example of an inherited workflow:
1818
1919
This approach ensures that all libraries in the ecosystem benefit from infrastructure updates without requiring manual changes to every repository.
2020

21+
For the protected-branch-safe preview and publish model, see
22+
:doc:`../advanced/branch-protection-and-bot-commits`.
23+
2124
Fast Forward Reports
2225
--------------------
2326

@@ -48,6 +51,8 @@ The ``wiki.yml`` workflow synchronizes the documentation generated by the ``dev-
4851

4952
.. note::
5053
See :doc:`../configuration/repository-setup` for mandatory initial setup required for the Wiki workflow to function.
54+
See :doc:`../advanced/branch-protection-and-bot-commits` for branch
55+
protection, bot commit, and submodule pointer conflict guidance.
5156

5257
Fast Forward Tests
5358
------------------

‎docs/usage/index.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,5 +11,6 @@ task-oriented guidance instead of class-by-class reference.
1111
testing-and-coverage
1212
documentation-workflows
1313
github-actions
14+
migrating-consumer-repositories
1415
syncing-packaged-skills
1516
syncing-consumer-projects

‎docs/usage/migrating-consumer-repositories.rst‎

Lines changed: 146 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,146 @@
1+
Migrating Consumer Repositories
2+
===============================
3+
4+
Use this guide when an existing PHP package repository is adopting
5+
``fast-forward/dev-tools`` for the first time. The goal is to introduce the
6+
shared Composer scripts, workflow stubs, wiki setup, skills, and repository
7+
defaults in a reviewable pull request.
8+
9+
This page complements :doc:`syncing-consumer-projects`; it focuses on the
10+
migration path instead of the full command reference.
11+
12+
Preflight Checks
13+
----------------
14+
15+
Before installing DevTools, confirm the repository has:
16+
17+
- a committed ``composer.json`` with the package name, PHP constraint, license,
18+
and autoload settings already reviewed;
19+
- a clean working tree;
20+
- a configured ``origin`` remote that points to the GitHub repository;
21+
- agreement on whether the repository should publish GitHub Pages reports and a
22+
GitHub Wiki;
23+
- a maintainer who can review workflow, Dependabot, and branch protection
24+
changes.
25+
26+
If the repository already has custom workflows or generated documentation, list
27+
the files that must be preserved before running sync. The sync command protects
28+
many existing files by default, but maintainers should still review the outcome
29+
as infrastructure code.
30+
31+
Install DevTools
32+
----------------
33+
34+
Install the package as a development dependency:
35+
36+
.. code-block:: bash
37+
38+
composer require --dev fast-forward/dev-tools
39+
40+
Commit the Composer changes separately only if the repository prefers very small
41+
review steps. For most migrations, it is reasonable to keep the Composer update
42+
and generated sync changes in the same pull request so reviewers can understand
43+
the complete automation model.
44+
45+
Run Sync Safely
46+
---------------
47+
48+
Run the sync command from the repository root:
49+
50+
.. code-block:: bash
51+
52+
composer dev-tools:sync
53+
54+
Then inspect the result before staging anything:
55+
56+
.. code-block:: bash
57+
58+
git status --short
59+
git diff
60+
61+
Expected changes can include:
62+
63+
.. list-table::
64+
:header-rows: 1
65+
66+
* - Area
67+
- Expected change
68+
- Review focus
69+
* - ``composer.json``
70+
- Adds shared ``dev-tools`` scripts and GrumPHP defaults.
71+
- Keep existing package metadata, scripts, and project-specific settings.
72+
* - ``.github/workflows/*.yml``
73+
- Adds thin workflow stubs that call reusable Fast Forward workflows.
74+
- Compare with any existing CI, release, docs, or Pages workflows.
75+
* - ``.editorconfig``
76+
- Adds the shared editor defaults when missing.
77+
- Confirm indentation and line-ending expectations match the project.
78+
* - ``.github/dependabot.yml``
79+
- Adds the shared Dependabot template when missing.
80+
- Confirm update cadence and ecosystem coverage.
81+
* - ``.github/wiki``
82+
- Adds the wiki submodule when missing.
83+
- Confirm the wiki repository exists and branch protection is compatible.
84+
* - ``.agents/skills``
85+
- Links packaged skills for issue, PR, tests, docs, README, and style work.
86+
- Preserve existing custom skills and non-symlink directories.
87+
* - ``LICENSE``
88+
- Adds the packaged license file when missing.
89+
- Confirm it matches the package metadata.
90+
* - ``.gitignore`` and ``.gitattributes``
91+
- Adds repository defaults when missing.
92+
- Keep existing project-specific ignores and export rules.
93+
94+
Handling Existing Custom Files
95+
------------------------------
96+
97+
When a target file already exists, treat the migration as a comparison exercise:
98+
99+
1. keep the existing file in place;
100+
2. compare it with the corresponding packaged file or workflow stub;
101+
3. copy only the entries that make sense for the repository;
102+
4. leave a pull request note explaining any intentional divergence.
103+
104+
This is especially important for custom CI workflows, release automation,
105+
repository-specific ``.gitignore`` rules, and existing Dependabot policies.
106+
Shared defaults are meant to reduce repeated maintenance, not erase local
107+
constraints.
108+
109+
Branch Protection and Bot Commits
110+
---------------------------------
111+
112+
Consumer repositories commonly protect ``main``. That is compatible with the
113+
Fast Forward model:
114+
115+
- pull requests receive generated previews and bot updates on the PR branch;
116+
- report previews are published under PR-specific Pages paths;
117+
- wiki previews use branches such as ``pr-123`` before merge;
118+
- post-merge jobs publish final reports and wiki content from ``main``.
119+
120+
If branch protection blocks bot commits to pull request branches, either adjust
121+
the repository policy to allow workflow updates on PR branches or document that
122+
maintainers must refresh generated pointers manually before merge.
123+
124+
Suggested Pull Request Rollout
125+
------------------------------
126+
127+
Use one migration pull request per consumer repository:
128+
129+
1. install ``fast-forward/dev-tools``;
130+
2. run ``composer dev-tools:sync``;
131+
3. review and adapt generated files;
132+
4. run the smallest relevant local verification command;
133+
5. open the pull request and let GitHub Actions create previews;
134+
6. verify report and wiki preview links before merge;
135+
7. merge through the protected ``main`` branch.
136+
137+
After merge, confirm that the final reports and wiki pages reflect the merged
138+
revision. If they do not, inspect the workflow logs before making follow-up
139+
changes.
140+
141+
Related References
142+
------------------
143+
144+
- :doc:`syncing-consumer-projects`
145+
- :doc:`syncing-packaged-skills`
146+
- :doc:`github-actions`

‎docs/usage/syncing-consumer-projects.rst‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,8 @@ The ``dev-tools:sync`` command is the bridge between this repository and the
55
libraries that consume it.
66

77
For the focused skills-only workflow, see :doc:`syncing-packaged-skills`.
8+
For a first-time adoption path, see
9+
:doc:`migrating-consumer-repositories`.
810

911
What the Command Changes
1012
------------------------

0 commit comments

Comments
 (0)