Skip to content

Merging existing repos into a monorepo

Devon Carew edited this page Sep 23, 2024 · 8 revisions
  1. Get git-filter-repo git clone https://github.com/newren/git-filter-repo.git
  2. Fresh clone of repo that needs to be merged into a mono repo:
    dart-lang $ git clone git@github.com:dart-lang/graphs.git

Automatic steps using package:trebuchet:

  1. Check that the local monorepo is in a fresh state.
  2. Run
git clone git@github.com:dart-lang/ecosystem.git
cd ecosystem/pkgs/trebuchet
dart run bin/trebuchet.dart \
  --input-name graphs \
  --branch-name master \
  --input-path ~/projects/graphs/ \
  --target tools \
  --target-path ~/projects/tools/ \
  --git-filter-repo ~/tools/git-filter-repo \
  --dry-run
  1. Do the same without the dry-run.
  2. Execute the remaining steps shown in the terminal.

Manual steps:

(Instructions in-lined from https://github.com/dart-lang/tools/pull/100.)

Steps taken for a sample graphs repo and target tools monorepo:

  1. Add git-filter-repo to PATH.
  2. Destructively rewrite the history of the repository to be in pkgs/package_name:
    graphs $ git filter-repo --path-rename :pkgs/graphs/
  3. Destructively prefix all the tags:
    graphs $ git filter-repo --tag-rename :graphs-
  4. Replace paths and links in files.
    1. Badges: https://github.com/dart-lang/graphs/actions/workflows/ci.yml -> https://github.com/dart-lang/tools/actions/workflows/graphs.yml
    2. Remaining links, manually check if this does the right thing, otherwise insert steps above this step. https://github.com/dart-lang/graphs -> https://github.com/dart-lang/tools/tree/main/pkgs/graphs
  5. Migrate the GitHub workflow.
    1. Delete dependabot.yaml which is already in the target mono_repo.
    2. Rename file: pkgs/graphs/.github/workflows/ci.yml -> .github/workflows/graphs.yml
    3. Add paths to the on clauses in the GitHub workflow (example).
    4. Add defaults->run->working-directory to all jobs in the GitHub workflow (example).
  6. Commit with a detailed message.
  7. In the directory of the mono_repo, create a branch.
    tools $ git checkout -b merge-graphs-package
  8. Add a remote for the local clone of the moving package
    1. tools $ git remote add graphs_package /Users/dacoharkes/src/dart-lang/graphs/
    2. tools $ git fetch graphs_package
  9. Merge tools $ git merge --allow-unrelated-histories graphs_package/master -m "Merge package:graphs into shared tool repository"
  10. Copy the list of renamed tags into a comment on the PR.
  11. Create a pull request and get it reviewed. Do not submit through the github UI, since it does not allow a fast forward merge.
    1. If there are changes required, back out and start over (it's OK to force push to the PR branch)
  12. Merging the PR:
    • Update the repo PR merge settings to enable "Allow merge commits"
    • Merge with a fast forward merge to the main branch ("Create a merge commit"); do not squash and merge
    • Update the repo PR merge settings to only "Allow squash merging"
  13. Push tags to github
  14. Follow up with a PR adding links to the top-level readme table.
  15. Add a commit to https://github.com/dart-lang/graphs/ with it's readme pointing to this repo
  16. Archive https://github.com/dart-lang/graphs/.