Media/WebRTC/libwebrtc Update Process Transition Plan
Before the new Media/WebRTC/libwebrtc_Update_Process can be executed, the existing copy of libwebrtc that exists in media/webrtc/trunk needs to be modified such that it will be as if it has gone through the new process. This is being tracked by Bug 1654147.
Contents
Build Changes
Currently libwebrtc must be located inside of media/webrtc/trunk, this must be made configurable such that code can be relocated. This is tracked by Bug 1654150.
Vendoring Script
We have a series of patches that remove unused files from libwebrtc, this speeds up the build and makes the executable smaller. In the new build process the files will be removed at the time that the library is vendored from Mozilla's Git repository. The vendoring script needs to be written, Bug 1654152, and we need to make sure that we have a minimal set of files.
File Removal
We can use ccov builds to identify other files that need to be removed from the tree. This process needs to be documented, as tracked by Bug 1654160. Removing the files is tracked by Bug 1654163.
Path Adjustment
After the build can be pointed at an out-of-tree copy of the library, it is likely that a number of paths will need to be fixed up. This is tracked by Bug 1654184.
Signaling Code
Then it should be possible to collapse the path media/webrtc/signaling/* into dom/media/webrtc/*. Which will once again require numerous path changes, and is tracked by Bug 1654185. This can happen at any time, and the sooner it happens the better.
nICEr and SIPCC
nICEr and SIPCC can be moved into their own repositories, tracked here Bug 1654194 and here 1654188. Then they can be moved into third_party, tracked here Bug 1654198 and here Bug 1654189. Doing all of this moving at once will cluster the Mercurial history changes together to avoid unwanted noise later.
Subdirectory Build-ability
Before the most recent WebRTC update it was possible to build the different sub directories of the media folder from mach. It would be extremely helpful to update process if we could get this back, as it would decouple building different sub components, such as peerconnection and mediaconduit. One could get a component building before moving onto the next. This is being tracked by Bug 1654205.
Migrating libwebrtc to GitHub
Motivation
There are a number of factors that make storing our soft fork of libwebrtc in Git appealing.
Our goal is to maintain as few, approaching zero, changes to the upstream version as possible. The upstream code is stored in a Git repository, so it makes it easier for us to upstream changes as we will no longer have to export patches. Likewise, it will make it easier to cherry pick patches from upstream.
By only removing files via the vendoring script, we will be able to more easily roll our version forward. As it is today, we will first need to undo all of our local deletions before we begin the merge process.
Process
Creating A New Repository To Track Upstream
The upstream tracking repository needs to be created in GitHub, which is tracked by Bug 1654435. This keeps the work in the native VCS, in a visible place with a review process.
Creating A User Repository To Hold The Merge Work
A Mozilla user repository has been created here. All of the revisions related to modifying Gecko during the merge will be kept here after being reviewed. There are instructions for making the repo publishing and for enabling support for obsolescence here
Generating GN files and updating the build
- Check out a version of the Google depot_tools which matches the fork date from upstream; this provides `gn`. See instructions here.
- Check out a copy of the version of libwebrtc to be vendored
- Add the version of `gn` that exists in the checkout to your path *ahead* of the version of `gn` included in the depot_tools
Source Control Process
The merge source code process strives to be easy to understand and execute.
Repositories
The merge changes are centrally stored on a Mercurial user repository hosted by Mozilla. This will allow the team to create a canonically ordered patch set to work off of day-to-day and it will eventually be landed with Lando on `autoland`. This repository is referred to as the `merge repo`. Additionally there exists a fork of the WebRTC native library repository on Github at mozilla/libwebrtc. As changes are made to libwebrtc within the merge, those changes will be gathered into a set of git commits to upstream. A second set of commits to retain but not upstream can also be maintained, but this set should be as close to empty as possible. During future libwebrtc merges the Github repository will be updated from the upstream google repository and our retained patches will be rebased on top of the new head. As of Sept. 3rd, we are moving from the user repository to a DisposableProjectRepositories named `Elm`. This is a repo for long running projects, and it can be referenced by a number of Mozilla's infrastructure facilities.
Process Flow
Developers will work on top of the merge repository. Those changes will be pushed to Phabricator for review. Once approved, a change set is push on top of the current tip of the merge repository, and the revision is closed in Phabricator. If further changes need to be made to the contents of the revision, those should be done in a new change set.
Reviews
Phabricator is used for reviews, just as it would be for non-merge work. Use the bug # for the main WebRTC merge revision (1654112). Consider making all reviewers blocking to avoid issues with change sets languishing due to lack of visibility after a single reviewer has accepted a patch.
Finalizing a Patch
Patches that pushed to the user repo, are finalized, and additional changes should be submitted as new patches. Once on the user repo, the patches should be closed in Phabricator.
Upstreaming libwebrtc Changes
See Upstreaming Changes to libwebrtc.
Shortcomings and Criticism
- Add your own here _______ !
External Tools
- It can be useful to check the upstream code with the codesearch.
Merge Related Documents
Please add links to any merge related documents here:
Lessons For The Next Merge
- Fork depot_tools at the same time as forking the main repo
- Investigate using `elder branches` which are real branches available on hg.mozilla.org
