1Partner attribution
2===================
3.. _partner attribution:
4
5In contrast to :ref:`partner repacks`, attributed builds only differ from the normal Firefox
6builds by the adding a string in the dummy windows signing certificate. We support doing this for
7full installers but not stub. The parameters of the string are carried into the telemetry system,
8tagging an install into a cohort of users. This a lighter weight process because we don't
9repackage or re-sign the builds.
10
11Parameters & Scheduling
12-----------------------
13
14Partner attribution uses a number of parameters to control how they work:
15
16* ``release_enable_partner_attribution``
17* ``release_partner_config``
18* ``release_partner_build_number``
19* ``release_partners``
20
21The enable parameter is a boolean, a simple on/off switch. We set it in shipit's
22`is_partner_enabled() <https://github.com/mozilla-releng/shipit/blob/main/api/src/shipit_api/admin/release.py#L93>`_ when starting a
23release. It's true for Firefox betas >= b8 and releases, but otherwise false, the same as
24partner repacks.
25
26``release_partner_config`` is a dictionary of configuration data which drives the task generation
27logic. It's usually looked up during the release promotion action task, using the Github
28GraphQL API in the `get_partner_config_by_url()
29<python/taskgraph.util.html#taskgraph.util.partners.get_partner_config_by_url>`_ function, with the
30url defined in `taskcluster/ci/config.yml <https://searchfox.org/mozilla-central/search?q=partner-urls&path=taskcluster%2Fci%2Fconfig.yml&case=true&regexp=false&redirect=true>`_.
31
32``release_partner_build_number`` is an integer used to create unique upload paths in the firefox
33candidates directory, while ``release_partners`` is a list of partners that should be
34attributed (i.e. a subset of the whole config). Both are intended for use when respinning a partner after
35the regular Firefox has shipped. More information on that can be found in the
36`RelEng Docs <https://moz-releng-docs.readthedocs.io/en/latest/procedures/misc-operations/off-cycle-partner-repacks-and-funnelcake.html>`_.
37
38``release_partners`` is shared with partner repacks but we don't support doing both at the same time.
39
40
41Configuration
42-------------
43
44This is done using an ``attribution_config.yml`` file which next lives to the ``default.xml`` used
45for partner repacks. There are no repos for each partner, the whole configuration exists in the one
46file because the amount of information to be tracked is much smaller.
47
48An example config looks like this:
49
50.. code-block:: yaml
51
52    defaults:
53        medium: distribution
54        source: mozilla
55    configs:
56        -   campaign: sample
57            content: sample-001
58            locales:
59            - en-US
60            - de
61            - ru
62            platforms:
63            - win64-shippable
64            - win32-shippable
65            upload_to_candidates: true
66
67The four main parameters are ``medium, source, campaign, content``, of which the first two are
68common to all attributions. The combination of ``campaign`` and ``content`` should be unique
69to avoid confusion in telemetry data. They correspond to the repo name and sub-directory in partner repacks,
70so avoid any overlap between values in partner repacks and atrribution.
71The optional parameters of ``variation``, and ``experiment`` may also be specified.
72
73Non-empty lists of locales and platforms are required parameters (NB the `-shippable` suffix should be used on
74the platforms).
75
76``upload_to_candidates`` is an optional setting which controls whether the Firefox installers
77are uploaded into the `candidates directory <https://archive.mozilla.org/pub/firefox/candidates/>`_.
78If not set the files are uploaded to the private S3 bucket for partner builds.
79
80
81Repacking process
82-----------------
83
84Attribution only has two kinds:
85
86* attribution - add attribution code to the regular builds
87* beetmover - move the files to a partner-specific destination
88
89Attribution
90^^^^^^^^^^^
91
92* kinds: ``release-partner-attribution``
93* platforms: Any Windows, runs on linux
94* upstreams: ``repackage-signing`` ``repackage-signing-l10n``
95
96There is one task, calling out to `python/mozrelease/mozrelease/partner_attribution.py
97<https://hg.mozilla.org/releases/mozilla-release/file/default/python/mozrelease/mozrelease/partner_attribution.py>`_.
98
99It takes as input the repackage-signing and repackage-signing-l10n artifacts, which are all
100target.exe full installers. The ``ATTRIBUTION_CONFIG`` environment variable controls the script.
101It produces more target.exe installers.
102
103The size of ``ATTRIBUTION_CONFIG`` variable may grow large if the number of configurations
104increases, and it may be necesssary to pass the content of ``attribution_config.yml`` to the
105script instead, or via an artifact of the promotion task.
106
107Beetmover
108^^^^^^^^^
109
110* kinds: ``release-partner-attribution-beetmover``
111* platforms: N/A, scriptworker
112* upstreams: ``release-partner-attribution``
113
114Moves and renames the artifacts to their public location in the `candidates directory
115<https://archive.mozilla.org/pub/firefox/candidates/>`_, or a private S3 bucket. There is one task
116for public artifacts and another for private.
117
118Each task will have the ``project:releng:beetmover:action:push-to-partner`` scope, with public uploads having
119``project:releng:beetmover:bucket:release`` and private uploads using
120``project:releng:beetmover:bucket:partner``. There's a partner-specific code path in
121`beetmoverscript <https://github.com/mozilla-releng/scriptworker-scripts/tree/master/beetmoverscript>`_.
122