taskcluster/docs/partner-attribution.rst

   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 full installers but not stub. The parameters of the string are carried into the telemetry system,
   8 tagging an install into a cohort of users. This a lighter weight process because we don't
   9 repackage or re-sign the builds.
  10
  11 Parameters & Scheduling
  12 -----------------------
  13
  14 Partner 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
  21 The 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
  23 release. It's true for Firefox betas >= b8 and releases, but otherwise false, the same as
  24 partner repacks.
  25
  26 ``release_partner_config`` is a dictionary of configuration data which drives the task generation
  27 logic. It's usually looked up during the release promotion action task, using the Github
  28 GraphQL API in the `get_partner_config_by_url()
  29 <python/taskgraph.util.html#taskgraph.util.partners.get_partner_config_by_url>`_ function, with the
  30 url 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
  33 candidates directory, while ``release_partners`` is a list of partners that should be
  34 attributed (i.e. a subset of the whole config). Both are intended for use when respinning a partner after
  35 the 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
  41 Configuration
  42 -------------
  43
  44 This is done using an ``attribution_config.yml`` file which next lives to the ``default.xml`` used
  45 for partner repacks. There are no repos for each partner, the whole configuration exists in the one
  46 file because the amount of information to be tracked is much smaller.
  47
  48 An 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
  66 The four main parameters are ``medium, source, campaign, content``, of which the first two are
  67 common to all attributions. The combination of ``campaign`` and ``content`` should be unique
  68 to avoid confusion in telemetry data. They correspond to the repo name and sub-directory in partner repacks,
  69 so avoid any overlap between values in partner repacks and atrribution.
  70 The optional parameters of ``variation``, and ``experiment`` may also be specified.
  71
  72 Non-empty lists of locales and platforms are required parameters (NB the `-shippable` suffix should be used on
  73 the platforms).
  74
  75 The Firefox installers are uploaded into the `candidates directory
  76 <https://archive.mozilla.org/pub/firefox/candidates/>`_.
  77
  78
  79 Repacking process
  80 -----------------
  81
  82 Attribution only has two kinds:
  83
  84 * attribution - add attribution code to the regular builds
  85 * beetmover - move the files to a partner-specific destination
  86
  87 Attribution
  88 ^^^^^^^^^^^
  89
  90 * kinds: ``release-partner-attribution``
  91 * platforms: Any Windows, runs on linux
  92 * upstreams: ``repackage-signing`` ``repackage-signing-l10n``
  93
  94 There is one task, calling out to `python/mozrelease/mozrelease/attribute_builds.py
  95 <https://hg.mozilla.org/releases/mozilla-release/file/default/python/mozrelease/mozrelease/attribute_builds.py>`_.
  96
  97 It takes as input the repackage-signing and repackage-signing-l10n artifacts, which are all
  98 target.exe full installers. The ``ATTRIBUTION_CONFIG`` environment variable controls the script.
  99 It produces more target.exe installers.
 100
 101 The size of ``ATTRIBUTION_CONFIG`` variable may grow large if the number of configurations
 102 increases, and it may be necesssary to pass the content of ``attribution_config.yml`` to the
 103 script instead, or via an artifact of the promotion task.
 104
 105 Beetmover
 106 ^^^^^^^^^
 107
 108 * kinds: ``release-partner-attribution-beetmover``
 109 * platforms: N/A, scriptworker
 110 * upstreams: ``release-partner-attribution``
 111
 112 Moves and renames the artifacts to their public location in the `candidates directory
 113 <https://archive.mozilla.org/pub/firefox/candidates/>`_.
 114
 115 Each task will have the ``project:releng:beetmover:action:push-to-partner`` and
 116 ``project:releng:beetmover:bucket:release`` scopes.  There's a partner-specific
 117 code path in `beetmoverscript
 118 <https://github.com/mozilla-releng/scriptworker-scripts/tree/master/beetmoverscript>`_.