EngineeringProductivity/HowTo/MirrorRepo

How to Mirror a Repository in Github to Mozilla-Central

Background

Many of our projects (such as mozbase and peptest) are version controlled with git and github, but are mirrored to mercurial and Mozilla-Central for the purposes of test infrastructure.

The reasoning is that tools and harnesses such as these are useful (or required) for Mozilla's test infrastructure, but are also useful as standalone utilities. Keeping them in github gives us greater development freedom, makes it easier for new contributors to help out and makes the tools more visible to people outside of the Mozilla community.

Steps

This guide uses git tags which are simply a way to assign a name to a commit. This tutorial will use mozbase as an example, though the workflow can apply to any project. Now suppose you fix a critical bug, or add a major new feature that is needed by the test infrastructure in Mozilla-Central (herein called m-c).

1. Write your patch for mozbase, attach it to your bug, get it reviewed, check it in to master and resolve the bug fixed as normal. Now it is time to mirror the latest master to m-c.
2. Create a new bug called "Mirror mozbase to m-c for xyz" or something like that and add your other bug as a depends on to make it clear why we are mirroring. It is often a good idea to bump the versions on pypi simultaneously with the m-c mirroring.
3. Copy the entire (up-to-date) mozbase folder from your git repository to the testing/mozbase directory in m-c. Do not include mozdevice, .git, .gitignore, or versionbump.py
4. Go to https://github.com/mozilla/mozbase/compare/mozilla-central...HEAD and examine the commits listed there. These are all the commits in master that aren't yet in m-c (i.e this is what you are committing to m-c). Pay special attention for commits that add or remove files and make sure to 'hg add' or 'hg rm' those exact same files in your m-c repository.
5. Generate a diff of m-c after you have copied the new mozbase there will files appropriately added and removed. Attach this to the bug.
6. Test your changes to make sure you didn't break the build using TryServer.
7. Get the attachment it reviewed, pushed to try and landed on mozilla-inbound. When mozilla-inbound is merged to m-c this bug can be marked fixed. Make sure your m-c commit message references the mozbase commit hash.
8. Create a git tag called 'mozilla-central' on your commit, you'll need to delete the old 'mozilla-central' tag. This way, the changeset tagged 'mozilla-central' will always keep track of the current state of mozbase in m-c:

git tag -d mozilla-central
git tag -a -m "mirrored to m-c" mozilla-central <git changeset of latest commit in m-c>
git push --tags origin master

Note: you can now once again go to https://github.com/mozilla/mozbase/compare/mozilla-central...HEAD to see the state of mozilla-central vs master.

A script has been written to aid in this effort: http://k0s.org/mozilla/mozbase/mc-diff.py . It currently hard-codes the path of a pristine mozilla-central clone and does not yet remove hg files removed from git, but other than that it is mostly a general solution to generate the diff