Media/WebRTC/libwebrtc Update Process

This page describes the process for updating the in tree, vendored copy of libwebrtc using the fast-forward scripts.

Operation Checklist

Prerequisites

• Create a new bug for the fast-forward update. It should depend on the previous fast-forward bug. Bug 1800920 is an example.
• Before each new merge cycle elm needs to be reset to Central.
  1. Ensure you have filed a bug for the next merge cycle, and further ensure that the next merge cycle bug has the previous merge cycle bug as a dependency.
  2. File a bug as a clone of Bug 1822294 and add your new bug as dependency to the next merge cycle bug.
  3. Wait for the repo admins to reset the repository.
  4. Celebrate
• Builds are done after vendoring in each commit. A minimal, default .mozconfig is provided during the prep_repo step below.
• Running the fast-forward process from macOS and Linux is supported. For more information on macOS, see here and here. TL;DR: If running from macOS, avoid Xcode and git while scripts are running, and you may also need to run this command ahead of time:

git config --global core.trustctime false

• Starting with a fresh clone of elm is recommended for each new chromium milestone.

hg clone --stream ssh://hg.mozilla.org/projects/elm

Update steps

# Start from the elm checkout
cd elm

# Update the default config file for the next upstream milestone
bash dom/media/webrtc/third_party_build/update_default_config.sh

# Prepare the github repo
bash dom/media/webrtc/third_party_build/prep_repo.sh

# Prepare no-op tracking files for cherry-pick commits
bash dom/media/webrtc/third_party_build/build_no_op_commits.sh

# Save the newly updated patch-stack - run this in a bash shell
(source dom/media/webrtc/third_party_build/use_config_env.sh ; \
 ./mach python dom/media/webrtc/third_party_build/save_patch_stack.py \
 --repo-path $MOZ_LIBWEBRTC_SRC \
 --target-branch-head $MOZ_TARGET_UPSTREAM_BRANCH_HEAD \
 --separate-commit-bug-number $MOZ_FASTFORWARD_BUG
)

# bootstrap and sanity build
./mach --no-interactive bootstrap --application-choice=browser && ./mach build

# Run loop-ff.sh
bash dom/media/webrtc/third_party_build/loop-ff.sh

Running prep-repo.sh with a fresh github clone of moz-libwebrtc will likely display instructions on how to add recent moz-central changes made in third_party/libwebrtc to the top of the patch stack in github. This is expected and necessary for successfully vendoring changes into third_party/libwebrtc.

Reacting to loop-ff.sh

Three main types of errors will cause loop-ff.sh to exit: the first is a git rebase conflict, the second is a failure to regenerate build files (due to BUILD.gn changes), and the third is a build error due to API changes in upstream code.

1. When fixing rebase errors or making other changes to fix build issues in moz-libwebrtc (any changes under third_party/libwebrtc), mercurial commit messages follow the pattern:

Bug {current-fast-forward-bug-number} - (fix-{upstream-sha}) {description}

# after following all the other instructions from loop-ff.sh (running the
# generation script for moz.build files, committing possible moz.build 
# changes and doing a build), run the following command:
(source dom/media/webrtc/third_party_build/use_config_env.sh ; 
 ./mach python dom/media/webrtc/third_party_build/save_patch_stack.py \
  --repo-path $MOZ_LIBWEBRTC_SRC \
  --target-branch-head $MOZ_TARGET_UPSTREAM_BRANCH_HEAD )

2. When making changes to fix Mozilla code (code outside of third_party/libwebrtc) in response to changes upstream, mercurial commit messages follow the pattern:

Bug {current-fast-forward-bug-number} (MOZ) - {description}

3. If instructed to run commit-build-file-changes.sh, its auto-generated mercurial commit messages follow the pattern:

Bug {current-fast-forward-bug-number} - (fix-{upstream-sha}) {description} - moz.build file updates

If multiple kinds of changes are needed, commit hygiene is appreciated: (MOZ) patches first, followed by the (fix-xxx) commit, followed by the script-generated "(fix-xxx) - moz.build file updates" — This order might require some effort if things don't build successfully right away (commit + build + amend).

Operational notes

• If loop-ff.sh reveals an issue that is best dealt with in a followup, one can commit a temporary patch marked with REPO-elm in the first line of its description, i.e. the "title". The temporary commit allows loop-ff.sh to continue, whereas REPO-elm makes sure the commit cannot be pushed to any other mozilla repo than elm (and try).
• While loop-ff.sh is running, in a separate terminal window it may be helpful to see the overall progress by running:

tail -f .moz-fast-forward/logs/log-loop-ff.txt | grep loop-ff

• GYP generated Java files
• If instructed to run extract-for-git.py, note that loop-ff.sh has more context than verify_vendoring.sh and offers information that is relevant: Specifically, the tip about tip::tip:

   If you have previously run loop-ff.sh successfully, there may be a new
   change to third_party/libwebrtc that should be extracted and added to
   the patch stack in github.  It may be as easy as running:
       ./mach python dom/media/webrtc/third_party_build/extract-for-git.py tip::tip
       mv mailbox.patch /Users/jan-ivar/moz/elm/.moz-fast-forward/moz-libwebrtc
       (cd /Users/jan-ivar/moz/elm/.moz-fast-forward/moz-libwebrtc && \
        git am mailbox.patch)

• Replace tip here with your (fix-xxx) mercurial patch, if it is not at tip (e.g. if it is followed by (fix-xxx) - moz.build file updates).

Backing out

• Stopping the loop-ff.sh manually is best done when in the Test build phase using Ctrl-c.
• If a particularly complicated rebase conflict is encountered, it is possible to start over the most recent vendoring step by resetting some state and restoring the patch stack.

rm .moz-fast-forward/*.resume # resets the resume logic in loop-ff.sh
hg revert third_party/libwebrtc && hg purge third_party/libwebrtc
./mach python dom/media/webrtc/third_party_build/restore_patch_stack.py --repo-path .moz-fast-forward/moz-libwebrtc

Review

• Simple changes don't require individual review, but if you'd feel better about getting reviewed, push the commit prior to elm (which will break all the builds). Then put the patch up for review. After r+, land it using Lando to elm.

Push to elm

# after the loop-ff.sh script completes, run the following steps
# to push the new version of libwebrtc to elm
./mach bootstrap --application=browser --no-system-changes
./mach build
hg push -r tip

Daily rebase on elm (after completing loop-ff process)

Periodically, ideally daily to minimize surprises from mozilla-central, rebasing elm onto the latest mozilla-central is recommended after completing the update process. Rebases should be completed until the request for merging elm to moz-central is made.

Historical note: we use a script to rebase because 1) it regenerates the moz.build files on the commits where those are changed. This avoids the typically massive rebase conflict if anyone has touched the build files. 2) it exports/imports each commit individually to limit rebase conflicts on individual patches, making it easier to deal with issues.

bash dom/media/webrtc/third_party_build/elm_rebase.sh

Requesting merge from elm to mozilla-central

Typically, immediately after the code-freeze has lifted, a request is made for the sheriffs to merge elm to mozilla-central. This done via email, recently to Sebastian Hengst.

Post-merge Steps

• After the merge from elm to mozilla-central is complete, the moz-libwebrtc github repo should be updated with the new branch of the commit stack for the new release. There is script that will make the proper branch name and do the push:

bash dom/media/webrtc/third_party_build/push_official_branch.sh