fix(wiki): restore direct publication without submodules by coisa · Pull Request #366 · php-fast-forward/dev-tools

coisa · 2026-10-13T07:20:12Z

Related Issue

Closes #365

Motivation / Context

Nine consumer Wiki workflows fail before execution because their old entry point no longer supports workflow_call. Use the direct publication model verified in php-fast-forward/container#15, with one shared implementation instead of copying it into every library.

Changes

Add wiki-direct.yml: read-only generation on PRs and a checkout-free publisher on main. Helpers and consumer renderer use the reviewed DevTools checkout; DevTools renders its own API from its checkout.
Publish Home.md and the generated classes/functions namespaces. Preserve other Wiki pages, reject symlinks/AGENTS/non-Markdown payloads, skip stale source revisions and queue writers without cancellation.
Remove only the parent Wiki gitlink and its .gitmodules entries; the remote Wiki/history remain intact.
Normal sync uses wiki --target=.dev-tools/wiki-generated rather than wiki --init. Explicit manual --init stays available.
Update root/packaged callers and docs. Maintenance entry/wrapper become manual-only migration guidance; legacy reusable callees remain available while existing consumers migrate.

Verification

Full composer dev-tools passed: 717 tests, 2,201 assertions, 91.83% line coverage; Rector, PHPDoc, ECS and documentation generation passed.
Focused SyncCommand regression failed before the change and passes after it (3 tests / 21 assertions).
Real Markdown generation from this checkout passed without a Wiki submodule.
Actual publisher Bash passed 54 offline assertions with disposable Git repositories, including manual preservation, stale API pruning, no-op, stale SHA rejection and unsafe-payload rejection. No remote Wiki was modified by these tests.
Composer validation, changelog check and diff check passed. Actionlint passed with only its obsolete schema warning for GitHub's supported concurrency.queue key excluded; the same queue:max setting is already exercised by container's successful workflow.

Documentation / Generated Output

README, wiki/sync command docs, workflow guide, architecture and AGENTS updated. Generated Markdown and docs were inspected.

Changelog

Added two Changed entries for direct publication and submodule-free sync.

Reviewer Notes

Consumer PRs will reference an exact commit of this workflow so their read-only generation can be tested before this PR merges. Merge the shared workflow before consumer adoption to keep normal DevTools synchronization aligned. Existing workflow targets need explicit migration or sync --overwrite.

Publication remains to be verified on each consumer after merge. Main can advance after the final source check but before the Wiki push; the queued newer publication catches up. The two repositories do not share an atomic write.

The full local gate reports pre-existing PHPmetrics warnings from malformed JUnit XML; PHPUnit itself reports zero warnings/risky tests. No unrelated metrics repair is included.

chatgpt-codex-connector · 2026-10-13T07:20:21Z

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-10-13T07:30:27.122641Z	`a286666`	PR opened
🔒 Security Review	✅ Completed 2026-10-13T07:26:32.531769Z	`a286666`	PR opened

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

coderabbitai · 2026-10-13T07:20:33Z

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Advanced
Run ID: a7c6bb39-a315-434b-bbe6-8f1a2998aaab

📥 Commits

Reviewing files that changed from the base of the PR and between d5a3b7e and a286666.

📒 Files selected for processing (16)

.github/wiki
.github/workflows/wiki-direct.yml
.github/workflows/wiki-maintenance-entry.yml
.github/workflows/wiki.yml
.gitmodules
AGENTS.md
CHANGELOG.md
README.md
docs/commands/sync.rst
docs/commands/wiki.rst
docs/internals/architecture.rst
docs/usage/github-actions.rst
resources/github-actions/wiki-maintenance.yml
resources/github-actions/wiki.yml
src/Console/Command/SyncCommand.php
tests/Console/Command/SyncCommandTest.php

💤 Files with no reviewable changes (2)

.gitmodules
.github/wiki

Included review availability: This review used your included allowance. Your plan provides up to 1 included review per hour; 0 remain after this review.

📝 Summary

Summary by CodeRabbit

New Features
- Wiki pages are now generated locally during sync, without initializing a wiki submodule.
- The wiki workflow publishes generated API pages from the main branch. Pull requests generate a read-only artifact without publishing changes.
Documentation
- Updated setup, workflow, and command guidance to reflect local generation and direct wiki publishing.
- Documented the legacy wiki initialization option and manual-only maintenance workflow.

The packaged Wiki workflow now generates API pages and publishes them to the separate GitHub Wiki repository from eligible main runs. Pull requests generate artifacts without Wiki write credentials. Normal sync generates Wiki Markdown locally instead of initializing a submodule.

Changes: Wiki publishing and generation

Layer / File(s)	Summary
Local Wiki generation `src/Console/Command/SyncCommand.php`, `tests/Console/Command/SyncCommandTest.php`, `README.md`, `docs/commands/*`, `docs/internals/architecture.rst`, `AGENTS.md`, `CHANGELOG.md`	Normal sync targets `.dev-tools/wiki-generated` instead of passing `--init`. The test checks the target and confirms that sync omits `--init`. Documentation describes local generation and retains `--init` as a legacy option.
Direct Wiki publication `.github/workflows/wiki-direct.yml`, `.github/workflows/wiki.yml`, `.github/workflows/wiki-maintenance-entry.yml`, `.github/wiki`, `.gitmodules`, `resources/github-actions/*`, `docs/usage/github-actions.rst`, `README.md`, `AGENTS.md`	The reusable workflow generates and validates Wiki pages, then publishes eligible `main`-run artifacts to the separate Wiki repository. The packaged caller invokes it; maintenance wrappers are manual-only notices. The `.github/wiki` reference and `.gitmodules` mappings are removed.

Priority: ➖ Normal

Estimated code review effort: 4 (Complex) | ~45 minutes

Change: Bug fix · Severity of issue fixed: Medium

Sequence Diagram(s)

sequenceDiagram
  participant GitHub
  participant Generation as Generation job
  participant Artifact
  participant Publication as Publication job
  participant Wiki as Wiki repository
  GitHub->>Generation: Start for push, pull request, or manual dispatch
  Generation->>Artifact: Upload generated pages
  opt main run that is not a pull request
    Publication->>Artifact: Download generated pages
    Publication->>GitHub: Check main source revision
    Publication->>Wiki: Replace Home.md, classes/, and functions/
  end

Suggested reviewers: php-fast-forward

Merge Risk: ⚪ Minimal · up to a2866

The reviewed changes are ready for normal merge checks. Publication to a consumer Wiki has not yet been exercised remotely.

Pre-merge checks · 5

Passed checks (5 passed)

Check name	Status	Explanation
Title check		The title clearly and concisely describes the main change: restoring direct Wiki publication without submodules.
Description check		The description includes all required sections and provides specific context, changes, verification results, documentation updates, changelog details, and reviewer notes.
Linked Issues check		Issue `#365` has coding requirements, and the PR implements them. `wiki-direct.yml` generates read-only artifacts for pull requests and publishes only for `main` through a separate Wiki checkout. The pu…
Out of Scope Changes check		The changed workflows, packaged callers, `SyncCommand`, tests, documentation, generated guidance, changelog, and removal of the Wiki submodule metadata all support the direct-publication and submodule…
Docstring Coverage		Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 2 functions across 2 files. (12 skipped: 1…

✨ Finishing Touches 💡 1

🛠️ Fix failing CI checks 💡

Commit to this branch
Create a new PR

📝 Generate docstrings

Commit to this branch
Create a new PR

🧪 Generate unit tests (beta)

Commit to this branch
Create a new PR

Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{A rabbit watched the pages grow,
Then sent them where the Wiki flows.
For pull requests, the pages stay read-only,
While main can publish them neatly.
Sync leaves Markdown close at hand,
No submodule burrows through the land.}

_{Comment @coderabbitai help to get the list of available commands.}

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: a286666dfc

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

chatgpt-codex-connector · 2026-10-13T07:30:23Z

+  wiki:
+    uses: ./.github/workflows/wiki-direct.yml


Remove the stale release-time wiki refresh

When this direct wrapper is adopted and .github/wiki is removed, the manual release flow still unconditionally invokes refresh-preview-pointer in .github/workflows/changelog.yml:277-283; that action immediately executes git -C .github/wiki fetch origin. Release preparation therefore fails after creating the release PR and before dispatching its required tests, both here and in migrated consumers.

AGENTS.md reference: AGENTS.md:L159-L173

Useful? React with 👍 / 👎.

chatgpt-codex-connector · 2026-10-13T07:30:23Z

+              $data['repositories']['pinned-dev-tools'] = [
+                  'type' => 'path',
+                  'url' => '.dev-tools-actions',
+                  'options' => ['symlink' => false, 'versions' => ['fast-forward/dev-tools' => 'dev-main']],


Make the pinned renderer installable for stable consumers

For a normal library consumer without composer.lock and with minimum-stability: stable, this path repository offers DevTools only as dev-main, so the subsequent composer install cannot satisfy a stable ^1.x requirement. With a lock file, install instead uses the exact locked version rather than this path checkout, as documented by Composer's install semantics; consequently the step either fails or runs an unpinned renderer instead of the selected revision.

AGENTS.md reference: AGENTS.md:L154-L164

Useful? React with 👍 / 👎.

chatgpt-codex-connector · 2026-10-13T07:30:23Z

@@ -1,18 +1,14 @@
-name: Update Wiki
+name: Fast Forward Wiki Update


Keep transient retries subscribed after renaming the workflow

Renaming the top-level workflow to Fast Forward Wiki Update disconnects it from .github/workflows/retry-transient-failures.yml:5-15, whose workflow_run.workflows filter still contains only Update Wiki and the legacy wiki names. Transient generation or publication failures from the replacement workflow will therefore no longer trigger the repository's automatic retry.

Useful? React with 👍 / 👎.

chatgpt-codex-connector · 2026-10-13T07:30:23Z

+* **Local sync:** ``dev-tools:sync`` generates Markdown in
+  ``.dev-tools/wiki-generated`` and does not initialize a Git submodule.


Align all canonical guides with the direct wiki flow

This now states that normal sync does not initialize a submodule, but docs/getting-started/installation.rst:13,43-44 and docs/usage/syncing-consumer-projects.rst:51-53,74,93-95 still tell consumers that sync creates .github/wiki and that the old preview/maintenance wrappers are active. Consumers following those canonical guides will retain obsolete setup and workflow expectations.

AGENTS.md reference: AGENTS.md:L203-L208

Useful? React with 👍 / 👎.

chatgpt-codex-connector · 2026-10-13T07:30:23Z

+      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+        with:
+          name: wiki
+          path: .dev-tools/wiki-generated


Upload the generated files from a non-hidden path

The pinned actions/upload-artifact excludes files within dot-directories by default, but this step uploads .dev-tools/wiki-generated without include-hidden-files: true. Consequently Home.md can pass the preceding test -s, yet the upload finds no eligible files and if-no-files-found: error fails every generation run before publication; the pinned action documents both the v4.4+ exclusion and the opt-in input in its README.

AGENTS.md reference: AGENTS.md:L170-L173

Useful? React with 👍 / 👎.

fix(wiki): publish directly and avoid automatic submodule initialization

a286666

github-actions Bot assigned coisa Oct 13, 2026

chatgpt-codex-connector Bot reviewed Oct 13, 2026

View reviewed changes

Navigation Menu

Repository navigation

fix(wiki): restore direct publication without submodules - #366

fix(wiki): restore direct publication without submodules#366
coisa wants to merge 1 commit into
mainfrom
codex/wiki-without-submodule

coisa commented Oct 13, 2026

Uh oh!

chatgpt-codex-connector Bot commented Oct 13, 2026 •

edited

Loading

Uh oh!

coderabbitai Bot commented Oct 13, 2026 •

edited

Loading

Summary by CodeRabbit

Sequence Diagram(s)

Uh oh!

chatgpt-codex-connector Bot left a comment

Uh oh!

chatgpt-codex-connector Bot Oct 13, 2026

Uh oh!

chatgpt-codex-connector Bot Oct 13, 2026

Uh oh!

chatgpt-codex-connector Bot Oct 13, 2026

Uh oh!

chatgpt-codex-connector Bot Oct 13, 2026

Uh oh!

chatgpt-codex-connector Bot Oct 13, 2026

Uh oh!

This branch has not been deployed

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

		@@ -1,18 +1,14 @@
		name: Update Wiki
		name: Fast Forward Wiki Update

		* Local sync: ``dev-tools:sync`` generates Markdown in
		``.dev-tools/wiki-generated`` and does not initialize a Git submodule.

Conversation

coisa commented Oct 13, 2026

Related Issue

Motivation / Context

Changes

Verification

Documentation / Generated Output

Changelog

Reviewer Notes

Uh oh!

chatgpt-codex-connector Bot commented Oct 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codex Review Summary

Uh oh!

coderabbitai Bot commented Oct 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary by CodeRabbit

Sequence Diagram(s)

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

chatgpt-codex-connector Bot Oct 13, 2026

Choose a reason for hiding this comment

Uh oh!

chatgpt-codex-connector Bot Oct 13, 2026

Choose a reason for hiding this comment

Uh oh!

chatgpt-codex-connector Bot Oct 13, 2026

Choose a reason for hiding this comment

Uh oh!

chatgpt-codex-connector Bot Oct 13, 2026

Choose a reason for hiding this comment

Uh oh!

chatgpt-codex-connector Bot Oct 13, 2026

Choose a reason for hiding this comment

Uh oh!

This branch has not been deployed

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

chatgpt-codex-connector Bot commented Oct 13, 2026 •

edited

Loading

coderabbitai Bot commented Oct 13, 2026 •

edited

Loading