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