Skip to content

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

Merged
coisa merged 3 commits into
mainfrom
codex/wiki-without-submodule
Oct 14, 2026
Merged

coisa merged 3 commits into
mainfrom
codex/wiki-without-submodule

Conversation

@coisa

@coisa coisa commented Oct 13, 2026 •

Copy link
Copy Markdown
Contributor

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.
  • Preserve consumer manifests/locks and plugin policy using an isolated pinned Composer renderer, explicit CLI/autoload paths, and its signed phpDocumentor binary and Markdown theme.
  • Guard release-time pointer refresh behind a real Wiki gitlink and retain automatic transient retries for the new workflow name.
  • Preserve the existing no-API skip using the canonical capabilities resolver; skip artifact upload and publication when no API is available. Align the remaining guides and clearly mark legacy preview/submodule instructions.
  • 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.

  • Follow-up: 24 focused checks passed for release gitlink detection, dispatch independence and isolated-generation selection. GitHub validates the revised renderer on the current commit.

  • No-API follow-up: 48 checks executed the actual generation shell and canonical resolver for no-autoload, missing directories, files-only and API-bearing fixtures. An API fixture with a missing Home.md still fails; no empty payload is published.

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

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

Copy link
Copy Markdown

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-14T19:30:03.471226Z fcbea51 Manual request
🔒 Security Review ✅ Completed 2026-10-14T19:33:03.946306Z fcbea51 Manual request
ℹ️ 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

coderabbitai Bot commented Oct 13, 2026 •

Copy link
Copy Markdown

Review in Change Stack →

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: 8a61dbad-7e03-4a73-b73a-4f4446108b4b
📥 Commits

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

📒 Files selected for processing: 6
  • .github/workflows/changelog.yml
  • .github/workflows/retry-transient-failures.yml
  • .github/workflows/wiki-direct.yml
  • docs/getting-started/installation.rst
  • docs/usage/github-actions.rst
  • docs/usage/syncing-consumer-projects.rst

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 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, docs/getting-started/installation.rst, docs/usage/syncing-consumer-projects.rst
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, resources/github-actions/wiki.yml, resources/github-actions/wiki-maintenance.yml, .github/workflows/retry-transient-failures.yml
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 retry workflow also recognizes completed runs of the Wiki update workflow.
Submodule removal and migration handling
.github/wiki, .gitmodules, .github/workflows/changelog.yml, AGENTS.md, README.md, CHANGELOG.md, docs/usage/github-actions.rst
The .github/wiki gitlink and .gitmodules mappings are removed. Release automation refreshes the Wiki preview only when the release pull request exists and the checkout contains the legacy gitlink. Documentation describes direct publication and migration from legacy workflows.

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
Loading
Merge Risk: ⚪ Minimal · up to c4433

The change moves Wiki publication to a main-only workflow using the repository token; the Wiki must be initialized first. Available evidence establishes no actionable publication failure or merge-blocking risk.

Pre-merge checks: Passed 5
Passed Passed checks: 5 passed
Check name Status Explanation
Linked Issues check Passed Issue #365 has coding requirements. The PR adds wiki-direct.yml with read-only PR generation and main-only publication through a separate Wiki checkout. The publisher preserves manual pages, repla…
Out of Scope Changes check Passed The workflow changes, packaged callers, sync change, tests, documentation, changelog, generated output, and Wiki submodule metadata removal directly support issue #365. The release guard and retry upd…
Docstring Coverage Passed 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. (6 skipped: 6 …
Title check Passed The title clearly identifies the main change: restoring direct Wiki publication without submodules.
Description check Passed The description includes all required sections and provides detailed context, changes, verification results, documentation updates, changelog entry, and reviewer notes.
✨ Finishing Touches
🧪 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

I’m a rabbit with pages to share,
I hop through the Markdown with care.
Pull requests make an artifact bright,
Main sends the pages to the Wiki at night.
Local sync leaves submodules behind,
And carrots of code are easy to find!

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

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 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".

Comment thread .github/workflows/wiki.yml
Comment thread .github/workflows/wiki-direct.yml Outdated
Comment thread .github/workflows/wiki.yml
Comment thread docs/usage/github-actions.rst
Comment thread .github/workflows/wiki-direct.yml
@coisa

coisa commented Oct 14, 2026

Copy link
Copy Markdown
Contributor Author

@codex review

@github-actions

Copy link
Copy Markdown
Contributor

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: c44339acd9

ℹ️ 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".

Comment thread docs/commands/sync.rst
Comment thread .github/workflows/wiki-direct.yml
@chatgpt-codex-connector

Copy link
Copy Markdown

🛡️ Codex Security Review · Automatically triggered

Security review completed. No security issues were found in this pull request.

Reviewed commit: c44339acd9

View security finding report

Only the user who started this review can view the report in Codex.

ℹ️ About Codex security reviews in GitHub

This is an experimental Codex feature. Security reviews are triggered when:

  • You comment "@codex security review"
  • A regular code review gets triggered (for example, "@codex review" or when a PR is opened), and you’re opted in so security review runs alongside code review

Once complete, Codex will leave suggestions, or a comment if no findings are found.

@coisa

coisa commented Oct 14, 2026

Copy link
Copy Markdown
Contributor Author

@codex review

@chatgpt-codex-connector

Copy link
Copy Markdown

Codex Review: Didn't find any major issues. Bravo.

Reviewed commit: fcbea51467

ℹ️ 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

Copy link
Copy Markdown

🛡️ Codex Security Review · Automatically triggered

Security review completed. No security issues were found in this pull request.

Reviewed commit: fcbea51467

View security finding report

Only the user who started this review can view the report in Codex.

ℹ️ About Codex security reviews in GitHub

This is an experimental Codex feature. Security reviews are triggered when:

  • You comment "@codex security review"
  • A regular code review gets triggered (for example, "@codex review" or when a PR is opened), and you’re opted in so security review runs alongside code review

Once complete, Codex will leave suggestions, or a comment if no findings are found.

@coisa
coisa merged commit c637e7f into main Oct 14, 2026
47 checks passed
@coisa
coisa deleted the codex/wiki-without-submodule branch October 14, 2026 19:36
@github-project-automation github-project-automation Bot moved this from Backlog to Released in PHP Fast Forward Project Oct 14, 2026
github-actions Bot added a commit that referenced this pull request Oct 14, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

Status: Released

Development

Successfully merging this pull request may close these issues.

Publish Wiki directly and stop recreating its submodule during sync

1 participant