Project:Mozilla/Version Bump Guide

This page provides scripts and general guidance on how to maintain several products offered by Mozilla in Gentoo. It is recommended to have a separate environment for development, e.g. a chroot, container, virtual machine and so. See Package_testing for specifics.

Some scripts to help with maintainer's tasks are available at https://github.com/juippis/my-gentoo-mozilla-scripts - they are referenced below. See the Readme file for a short introduction to these scripts.

General notes
I recommend using the provided scripts, and a dedicated test environment for these bumps. the script repo and add the directory to your user's. before working on Mozilla products in Gentoo (or just occassionally).

Other tools that are recommended: pkg-testing-tools in your test environment, gentoolkit in your host, pkgcheck in your host.

Join the other project members in Libera.chat's #gentoo-mozilla channel!

General resources: https://firefox-source-docs.mozilla.org/index.html

Firefox
https://wiki.mozilla.org/Release_Management/Calendar

https://wiki.mozilla.org/NSS:Release_Versions

Only Firefox-ESR gets stabilized.

Firefox ESR major version bump
When bumping major ESR version, e.g., from 78 to 91, it's better to base the ebuild on the new parallel rapid version. Upon release, rapid and esr will have their development branches diverged immediately, so in theory rapid-91.0.2 and esr-91.0.2 can be different, but in practice probably not.

It's suggested to still keep offering old ESRs before the new one is "officially" released and biggest bugs weeded out, Mozilla will usually take a while before the new ESR is "production-ready" even if it's offered, and old ESR is kept alive for few months.

NSS
https://wiki.mozilla.org/NSS:Release_Versions

Each version gets a detailed "release notes" shipped by upstream. After unpacking the sources, see. Or head to https://hg.mozilla.org/projects/nss/file/tip/doc/rst/releases

Upstream includes their CI scripts and configs in the release tarball, so the directory can be studied for packaging help.

NSS's build documentation recommends to use gyp to build nss, but upstream says otherwise. There's some work currently on-hold regarding gyp support.

Only NSS-ESR gets stabilized.

Spidermonkey
Spidermonkey's sources get shipped with Firefox-ESR's source tarball. The rapid version of Spidermonkey is often broken and should not be used. Therefore Spidermonkey's ebuild follows closely Firefox-ESR's. Spidermonkey should match Firefox-ESR's patch set, but also its own spidermonkey patch set in Gentoo. FIREFOX_PATCHSET="firefox-91esr-patches-05j.tar.xz" SPIDERMONKEY_PATCHSET="spidermonkey-91-patches-03j.tar.xz"

I.e., for spidermonkey-91.7.1 match the patch set used in if firefox-91.7.1.

https://github.com/mozilla/gecko-dev/tree/master/js

https://github.com/mozilla-spidermonkey/spidermonkey-embedding-examples/tree/next

https://github.com/mozilla-spidermonkey/spidermonkey-embedding-examples/tree/next/docs

https://github.com/mozilla-spidermonkey/spidermonkey-embedding-examples/tree/next/.github/workflows CI configuration.

Thunderbird
Thunderbird is built on top of Firefox-ESR and a new version is often released just a couple of days after Firefox-ESR. Not every ESR change goes to Thunderbird, and therefore not every Firefox-ESR is followed by a new Thunderbird release. E.g, purely cosmetic changes don't usually warrant a new Thunderbird release.

As a general note, whatever was done with the matching Firefox-ESR's ebuild has to be replicated on to Thunderbird as well. Firefox-ESR and Thunderbird share their Gentoo patch sets, e.g. FIREFOX_PATCHSET="firefox-91esr-patches-06j.tar.xz" is replicated in Thunderbird as well.

https://www.thunderbird.net/en-US/thunderbird/releases/

Periodic Maintainer checks
Use packages.gentoo.org or gentoo_mozilla_maintainer_check.sh to check occassionally for maintainer's tasks. Add yourself to Mozilla's mail alias to receive notifications from bugzilla, and mails directly to the alias. bugs assigned to mozilla@g.o.

cbindgen
Launch your container or other dedicated test environment. Install cargo-ebuild.

modify ebuild here. Add unstable keywords from the previous ebuild e.g. . Add https://github.com/eqrion/cbindgen/archive/refs/tags/v${PV}.tar.gz -> ${P}.tar.gz to  if needed. Remember to run again after. Add  to prevent rust-related QA warnings from popping up. Proceed testing it with

Do reverse-bdep testing, https://packages.gentoo.org/packages/dev-util/cbindgen/reverse-dependencies

Firefox
For major version bumps (e.g. 95.0.3 -> 96.0), use the gentoo_mozilla_products_vbump_differ.sh script to sniff out any relevant changes done in the build system. More relevant files are listed at the top. Firefox-bin packages can be bumped pretty much after shows differences, or no differences.

For minor version bumps (e.g. 98.0 -> 98.0.1), there's usually less than 10 changes so they can most likely be checked from Mozilla's mercurial web interface. Although it doesn't hurt to run the gentoo_mozilla_products_vbump_differ.sh for those either.

https://hg.mozilla.org/releases/mozilla-release/log rapid

https://hg.mozilla.org/releases/mozilla-esr91/log ESR

Sort out patching if you've been following upstream bugs and are aware some patches are redundant, or if some additional ones are needed. See Patches and Patching. Open up a container, chroot or whatever is your preferred way of testing new ebuilds.

Do your ebuild modifications. (It's good to test the new patch set applies with a simple . For major version bumps it's good to do a single run with default USE flags:

If it passes, use the proper script to test it.

Even for minor bumps it's good to do a thorough testing, since sometimes updated dependencies might be the cause of new failures. E.g. media-libs/dav1d and libvpx are infamous for that. Do runtime testing between builds if possible.

With good package-testing-settings your terminal output will show the final size for the build directory. These can be found from saved elogs too. Example:

no pgo, no lto * Final size of build directory: 6879180 KiB ( 6.5 GiB) * Final size of installed tree:  278032 KiB (271.5 MiB)

gcc, +lto +pgo * Final size of build directory: 13954940 KiB ( 13.3 GiB) * Final size of installed tree:   228356 KiB (223.0 MiB)

Increase the size requirements in the ebuild if needed.

nss
Open up chroot, container etc. Copy and edit the ebuild as needed. Fist do a basic installation to see that patches apply, and that it compiles with default USE flags.

Install libabigail and iwdevtools if you don't have them already.

Edit the ebuild if needed.

Then do few test runs with pkg-testing-tools,

Testing reverse dependencies wouldn't hurt at this point either, but if qa-cmp didn't report any significant changes, it may not be that important.

https://qa-reports.gentoo.org/output/genrdeps/rindex/dev-libs/nss

A very simple rdeptester.sh.

nspr
Run the script to find important build-related differences between versions:

Open up chroot, container etc. Copy and edit the ebuild as needed. Fist do a basic installation to see that patches apply, and that it compiles.

Remember to ekeyword ~all nspr-4.34.ebuild your new.

Install libabigail and iwdevtools if you don't have them already, and check there are no breaking library changes.

Do better test runs with stricter. This will also run  once.

Do reverse dependency testing, just in case.

Spidermonkey
Again, remember to replicate whatever was done in Firefox-ESR's ebuild between the changed versions. Base a major version bump (e.g., 78 -> 91) in Firefox-ESR's ebuild.

Update patch set if needed. Start a container, chroot etc. Edit the ebuild as needed. Always good to do a light run to test that patches apply and that the package compiles with default USE flags etc.

Install libabigail and iwdevtools if you don't have them already.

Do a thorough test run.

Thunderbird
Firefox-ESR should be bumped at this point. Base the initial work on that, e.g. update patch set to match Firefox-ESR-91.5.0.

Do your ebuild modifications. (It's good to test the new patch set applies with a simple . For major version bumps it's good to do a single run with default USE flags:

If it passes, use the proper script to test it.

Even for minor bumps it's good to do a thorough testing, since sometimes updated dependencies might be the cause of new failures. E.g. media-libs/dav1d and libvpx are infamous for that. Do runtime testing between builds if possible.

Patches and Patching
All firefox patches are stored in a directory that's compressed and downloaded via. See the  variable in the ebuild. Originally the patches were based on git repository submissions, but I haven't been able to find the origin of this repository, so now the patches are just named in git-format for consistency's sake.

Try to use a consistent patch naming convention. "PN"-"majorversion"-patches-"revision".tar.xz.

For single patch files inside the tarball, we attempt to link it to a relevant Gentoo/Mozilla bug via the filename. E.g.,.

Now wget / copy your new patch here, note the naming convention.

Upload the file to your devspace.

Update  variable in the new ebuild.

If you need to remove an older patch due to upstream fixing it etc, do