Backporting a mozilla central patch

This is a collection of notes that should make it easier for people to backport a patch from mozilla-central to this GitHub repository in the case it's needed. Note that this guide assumes you're using the Git-workflow for mozilla-central, and will not work if you're on Mercurial.

Discover if things changed

There are a couple of ways you can figure out if stuff changed.

• Just export the sources into m-c and see if there are any unexpected changes. But that's not really great.
• Run git log browser/extensions/webcompat/ inside mozilla-central, which will only show you the commits that changed something in the addon.

Generate a patch from a commit in mozilla-central

1. Find out the git hash for the commit you want to backport.
   • If you know the Mercurial hash, you can use git cinnabar hg2git [the mercurial commit hash], which will show you the Git commit hash in your local repository.
   • If you don't know the Mercurial hash, just check git log.
2. Change into the directory of the extension, cd browser/extensions/webcompat.
3. Run git format-patch -1 [git commit hash] --relative .. This will create a .patch file in the current directory.

Apply a generated patch

1. Make sure your local clone is on the main branch and updated.
2. Run git am -3 --directory src/ [path to the .patch file generated]
3. If the patch you're applying contains a version number change in manifest.json, make sure to run npm run autoformat so that the changed version number is also applied in package{,-lock}.json. git commit --amend the version number change to the backported commit. Otherwise, your push will fail Ci!
4. Make sure to push the changes. Pushing commits directly to main is usually fine, because the changes are in central anyway. If you're unsure, push the changes into a separate branch or a fork and open a PR for review.

This should apply the changes, and carry over commit information like timestamps and author information. Conflicts can occur if the patch is old and the GitHub version changed too much. Resolving conflicts is the same as resolving merge conflicts.

Resolving conflict: error: sha1 information is lacking or useless

If the patch doesn't apply, with an error message that is similar to

error: sha1 information is lacking or useless (src/manifest.json).
error: could not build fake ancesto

you have to apply that patch "manually". To do so,

1. Run git am --show-current-patch=diff | patch -p1 -d src. patch will try its best to apply the changes.
2. If you see errors like Hunk #1 FAILED, something could not be applied. You'll find the change that can't be applied in a .rej file. Open a text editor and resolve those cases manually.
3. Make sure that all .rej and .orig files are either taken care off and/or deleted. Check git status to make sure only valid changes are tracked.
4. Add all changes with git add -A, then run git am --continue.

Your patch should be backported, and you can git push.