Skip to documentation

Migrating Consumer Repositories

Use this guide when an existing PHP package repository is adopting fast-forward/dev-tools for the first time. The goal is to introduce the shared Composer scripts, workflow stubs, wiki setup, skills, and repository defaults in a reviewable pull request.

This page complements Syncing Consumer Projects; it focuses on the migration path instead of the full command reference.

Preflight Checks

Before installing DevTools, confirm the repository has:

  • a committed composer.json with the package name, PHP constraint, license, and autoload settings already reviewed;
  • a clean working tree;
  • a configured origin remote that points to the GitHub repository;
  • agreement on whether the repository should publish GitHub Pages reports and a GitHub Wiki;
  • a maintainer who can review workflow, Dependabot, and branch protection changes.

If the repository already has custom workflows or generated documentation, list the files that must be preserved before running sync. The sync command protects many existing files by default, but maintainers should still review the outcome as infrastructure code.

Install DevTools

Install the package as a development dependency:

composer require --dev fast-forward/dev-tools

Commit the Composer changes separately only if the repository prefers very small review steps. For most migrations, it is reasonable to keep the Composer update and generated sync changes in the same pull request so reviewers can understand the complete automation model.

Run Sync Safely

Run the sync command from the repository root:

composer dev-tools:sync

Then inspect the result before staging anything:

git status --short
git diff

Expected changes can include:

Area Expected change Review focus
composer.json Adds shared dev-tools scripts and GrumPHP defaults. Keep existing package metadata, scripts, and project-specific settings.
.github/workflows/*.yml Adds thin workflow stubs that call reusable Fast Forward workflows. Compare with any existing CI, release, docs, or Pages workflows.
.editorconfig Adds the shared editor defaults when missing. Confirm indentation and line-ending expectations match the project.
.github/dependabot.yml Adds the shared Dependabot template when missing. Confirm update cadence and ecosystem coverage.
.dev-tools/wiki-generated Generates local API Markdown without creating a submodule. Review the generated pages and direct Wiki workflow configuration.
.agents/skills Links packaged skills for issue, PR, tests, docs, README, and style work. Preserve existing custom skills and non-symlink directories.
.agents/agents Links packaged project agents for issue, PR, docs, README, and AGENTS maintenance work. Preserve existing custom agents and non-symlink directories.
LICENSE Adds the packaged license file when missing. Confirm it matches the package metadata.
.gitignore and .gitattributes Adds repository defaults when missing. Keep existing project-specific ignores and export rules.

Handling Existing Custom Files

When a target file already exists, treat the migration as a comparison exercise:

  1. keep the existing file in place;
  2. compare it with the corresponding packaged file or workflow stub;
  3. copy only the entries that make sense for the repository;
  4. leave a pull request note explaining any intentional divergence.

This is especially important for custom CI workflows, release automation, repository-specific .gitignore rules, and existing Dependabot policies. Shared defaults are meant to reduce repeated maintenance, not erase local constraints.

When adopting direct Wiki publication, update an existing wiki.yml wrapper explicitly to call wiki-direct.yml and remove automatic maintenance triggers. Normal sync preserves existing workflow files by default. The packaged wiki-maintenance.yml is a manual-only migration notice; legacy reusable preview and maintenance workflows remain available for unmigrated callers.

Remove only the obsolete .github/wiki gitlink and its matching .gitmodules stanza, preserving other submodules and the separate GitHub Wiki repository. Local sync does not remove an existing pointer automatically.

Branch Protection and Bot Commits

Consumer repositories commonly protect main . That is compatible with the Fast Forward model:

  • pull requests receive generated previews and bot updates on the PR branch;
  • report previews are published under PR-specific Pages paths;
  • the direct Wiki workflow generates a read-only artifact on pull requests, without publishing a preview branch or committing a submodule pointer;
  • post-merge jobs publish final reports and wiki content from main .

If branch protection blocks bot commits to pull request branches, either adjust the repository policy to allow workflow updates on PR branches or document that maintainers must apply those bot-managed changes manually before merge.

Suggested Pull Request Rollout

Use one migration pull request per consumer repository:

  1. install fast-forward/dev-tools ;
  2. run composer dev-tools:sync ;
  3. review and adapt generated files;
  4. run the smallest relevant local verification command;
  5. open the pull request and let GitHub Actions create previews;
  6. verify report preview links and the generated Wiki artifact before merge;
  7. merge through the protected main branch.

After merge, confirm that the final reports and wiki pages reflect the merged revision. If they do not, inspect the workflow logs before making follow-up changes.

Related References

Search results