1 files changed, 132 insertions, 0 deletions
diff --git a/build/docs/snap.rst b/build/docs/snap.rst
new file mode 100644
index 0000000000..6ff52da4e8
--- /dev/null
+++ b/build/docs/snap.rst
@@ -0,0 +1,132 @@
+.. _snap:
+
+======================
+Firefox Snap Packaging
+======================
+
+This page explains interactions between Firefox and Snap packaging format.
+
+Where is the upstream
+=====================
+
+The code reference itself is mozilla-central, but the packaging is being worked
+within the `Canonical's firefox-snap repository <https://github.com/canonical/firefox-snap/>`_.
+
+This packaging includes a few more bits and dependencies, including compiler.
+It will also re-download the mercurial repository: this is on purpose.
+
+Where to report bugs
+====================
+
+All bugs should be reported to Bugzilla's ``Third Party Packaging`` component,
+and marked as blocking ``snap`` meta-bug.
+
+Build process
+=============
+
+While there is an existing ``repackage`` `task
+<https://searchfox.org/mozilla-central/source/taskcluster/docker/firefox-snap>`_,
+is currently is no up-to-date and it is not usable from ``mach`` (work is being
+`tracked in <https://bugzilla.mozilla.org/show_bug.cgi?id=1841370>`_ for this),
+so unfortunately the only way to work right now is a full rebuild using
+upstream tooling.
+
+The following steps should be enough, assuming you have properly setup:
+
+ - ``snapcraft`` (see `quickstart doc <https://snapcraft.io/docs/snapcraft-quickstart>`_)
+ - ``LXD`` (see `providers doc <https://snapcraft.io/docs/build-providers>`_)
+
+While the documentation still refers to `Multipass`, the Firefox Snap and its
+dependency had some requirements that made it better suited to use `LXD`.
+
+When performing the checkout, please keep in mind the branch mapping:
+
+ - `edge` is our `nightly`
+ - `beta` is our `beta`
+ - `stable` is our `release`
+ - `esr` is our `esr`
+
+.. code-block:: shell
+
+    $ git clone https://github.com/canonical/firefox-snap --branch BRANCH
+    $ snap run snapcraft
+
+You should end up after some time with two files: ``firefox-XXX.snap`` and
+``firefox-XXX.debug``. The first one is the package you will want to ``snap
+install`` while the second one holds your debugging symbols.
+
+You can then install the package:
+
+.. code-block:: shell
+
+    $ sudo snap install --name firefox --dangerous ./path/to/firefox-XXX.snap
+
+If you want to have parallel installs, then you can change the `--name firefox`
+to something else. This will be the name you use for ``snap run
+installed-name``, e.g., ``--name firefox_nightly`` will require you to run
+``snap run firefox_nightly``.
+
+`Snap` has a notion of plugs and slots, and some gets automatically connected
+in various ways, including depending on the ``Snap Sore`` itself, and if you
+manually install as ``firefox`` it should reuse them (but you might do bad
+things with your profile). If you install using another name, then the ``Snap
+Store`` automatic connection will not happen and this can result in a broken
+state. Inspecting ``snap connections firefox`` using a store-installed snap
+should get your an accurate list that you can replicate.
+
+What CI coverage
+================
+
+Currently, there are upstream-like builds on treeherder. They are scheduled as
+a cron task daily and includes:
+
+ - building opt/debug versions of the snap
+ - building them on all branches
+ - running a few selenium-based tests
+
+The build definitions `are based on docker <https://searchfox.org/mozilla-central/rev/3c72de9280ec57dc55c24886c6334d9e340500e8/taskcluster/docker/snap-coreXX-build/Dockerfile>`_.
+
+It should be noted that for the moment, all tasks needs to run under docker.
+However, this setup is not working for `Snap` since it interacts with `SystemD`
+which does not work under `Docker`. This is why the installation is handled by
+`the install-snap script
+<https://searchfox.org/mozilla-central/rev/3c72de9280ec57dc55c24886c6334d9e340500e8/taskcluster/docker/snap-coreXX-build/install-snap.sh>`_
+rather than plain `sudo snap install`, and also why we need to run `snap` in
+`destructive mode` (which is fine since we are within a docker container). This
+does not apply to the tests case which relies on newly-available wayland
+virtual machines.
+
+Outside the build oddities because of the setup, it should be noted that those
+builds are as close as possible to upstream. This means:
+
+ - the mozilla-central hash they run against is not matching the source code it
+   builds from, and one should inspect the build log to see the mercurial clone
+   step
+ - it builds using the clang build within the snap definition
+
+The tests are defined `within the docker subdirectory
+<https://searchfox.org/mozilla-central/rev/3c72de9280ec57dc55c24886c6334d9e340500e8/taskcluster/docker/snap-coreXX-build/snap-tests/tests.sh>`_.
+They are using Selenium because this is what was used by pre-existing tests ran
+on GitHub Actions from upstream.
+
+Their coverage is ensuring that we get a basic working browser out of builds.
+It includes some tests that previously were manually ran by QA.
+
+How to hack on try
+==================
+
+Build and test tasks can be explored via ``mach try fuzzy --full`` by searching
+for ``'snap 'upstream``. There is a bit of hacking for try to make sure we
+actually don't re-download the mercurial repo and directly reuse the clone
+generated by `run-task`, handled in the `run.sh script
+<https://searchfox.org/mozilla-central/rev/3c72de9280ec57dc55c24886c6334d9e340500e8/taskcluster/docker/snap-coreXX-build/run.sh#61-72>`_.
+
+So pushing to try is basically just:
+
+.. code-block:: shell
+
+    $ mach try fuzzy --full -q "'snap 'upstream 'try"
+
+Because of the build process, a full opt build will take around 1h45-2h while a
+debug build will be around 60 minutes, the difference coming from the use of
+PGO on opt builds.