Skip to content

Add migration guide for consumer repositories #72

@coisa

Description

@coisa

Objective

Add a migration guide for consumer repositories adopting Fast Forward DevTools.

Current Limitation

The project documents installation and sync commands, but consumer maintainers would benefit from a guided migration path that explains what will change, how to review those changes, and how to roll out automation safely.

Proposed Work

Create a step-by-step migration guide for taking an existing PHP package repository from no dev-tools integration to synchronized Fast Forward automation.

Scope

  • Preflight checks before installing dev-tools.
  • Composer installation command and expected package changes.
  • Running dev-tools:sync safely.
  • Reviewing generated workflows, .editorconfig, Dependabot, wiki submodule, skills, license, Git hooks, .gitignore, and .gitattributes changes.
  • Handling branch protection and bot commits.
  • Suggested PR rollout strategy for consumer repositories.

Non-goals

  • Replacing the quickstart.
  • Covering non-PHP projects.
  • Automating migration in this issue.

Acceptance Criteria

Delivery Criteria

  • A consumer migration guide exists under docs/usage or docs/getting-started.
  • The guide explains expected file changes from sync.
  • The guide includes a safe review workflow for maintainers.
  • The guide references relevant command docs.
  • The guide covers how to handle existing custom workflows and config files.

Architectural / Isolation Criteria

  • The guide builds on existing docs rather than duplicating full command references.
  • Examples use Fast Forward repository conventions consistently.

Metadata

Metadata

Assignees

Labels

documentationImprovements or additions to documentation

Type

No type

Projects

Status

Released

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions