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.

- Builds are done after vendoring in each commit. Having a .mozconfig file that enables cache (either sccache or ccache) will improve the performance of the scripts.

hg clone https://hg.mozilla.org/projects/elm
(cd elm && ./mach bootstrap --application-choice=browser && ./mach build)
git clone https://github.com/mozilla/libwebrtc moz-libwebrtc

Update steps

# Start from the elm checkout
cd elm

# 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

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

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

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

bash dom/media/webrtc/third_party_build/elm/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

- Update the example config file for the next fast-forward operation. This should be done in a separate bug, but if it has not been done prior, can be done at the beginning of the fast-forward operation as the first commit on elm.

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

- Follow the Resetting_Elm steps below.

Operational notes

- 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.

- Two main types of errors will cause loop-ff.sh to exit; the first is a rebase conflict, the second is a build error due to api changes in upstream code.

- When making changes to fix build issues in moz-libwebrtc, mercurial commit messages follow the pattern:

Bug xxx - (fix-{upstream-sha}) {description}

- When making changes to fix Mozilla code in response to changes upstream, mercurial commit messages follow the pattern:

Bug xxx (MOZ) - {description}

- While loop-ff.sh is running, in a separate terminal window it may be helpful to see the overall progress by running:

tail -f ~/log-loop-ff.txt | grep loop-ff

- If a particularly complicated rebase conflict is encountered, it is helpful to tar up the moz-libwebrtc directory to allow a complete reset without losing current progress.

(cd {path-to}/moz-central && rm log_resume.txt) # resets the resume logic in loop-ff.sh
(cd {path-to}/moz-libwebrtc && git rebase --abort) # don't finish this rebase
(cd {path-to}/moz-libwebrtc/.. && tar czf moz-libwebrtc.tar.gz && cd moz-libwebrtc)

- Stopping the loop-ff.sh manually is best done when in the Test build phase using Ctrl-c.

Resetting Elm

Before each new merge cycle. Elm needs to be reset to Central, and the floating patches need to be reapplied.

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. Make sure you have a local checkout of Elm which includes the floating patches.
3. File a bug as a clone of Bug 1789675 and add your new bug as dependency to the next merge cycle bug.
4. Wait for the repo admins to reset the repository.
5. Mark the floating arc config patch with a bookmark. If the patch had id `5e8481a558fb` then one would run

   hg bookmark -r 5e8481a558fb ARC_CONFIG_FLOAT
   

6. Pull the new head of Elm.

   hg pull
   

7. Rebase the floating patches onto the new checkout of Elm, then checkout the new tip.

   hg rebase --keep -s ARC_CONFIG_FLOAT -d elm && \
   hg co tip && \
   hg bookmark ARC_CONFIG_FLOAT
   

8. Push the floating patches to Elm.

   hg push --bookmark=ARC_CONFIG_FLOAT
   

9. Celebrate