taskcluster/docs/versioncontrol.rst

   1 =====================
   2 Version Control in CI
   3 =====================
   4
   5 Upgrading Mercurial
   6 ===================
   7
   8 Upgrading Mercurial in CI requires touching a handful of different
   9 components.
  10
  11 Vendored robustcheckout
  12 -----------------------
  13
  14 The ``robustcheckout`` Mercurial extension is used throughout CI to
  15 perform clones and working directory updates. The canonical home of
  16 the extension is in the
  17 https://hg.mozilla.org/hgcustom/version-control-tools repository
  18 at the path ``hgext/robustcheckout/__init__.py``.
  19
  20
  21 When upgrading Mercurial, the ``robustcheckout`` extension should also
  22 be updated to ensure it is compatible with the version of Mercurial
  23 being upgraded to. Typically, one simply copies the latest version
  24 from ``version-control-tools`` into the vendored locations.
  25
  26 The locations are as follows:
  27
  28 - In-tree: ``testing/mozharness/external_tools/robustcheckout.py``
  29 - Treescript: ``https://github.com/mozilla-releng/treescript/tree/master/treescript/py2/robustcheckout.py``
  30 - build-puppet: ``https://github.com/mozilla-releng/build-puppet/blob/master/modules/mercurial/files/robustcheckout.py``
  31
  32
  33 Debian Packages for Debian Based Docker Images
  34 ----------------------------------------------
  35
  36 ``taskcluster/ci/packages/kind.yml`` defines custom Debian packages for
  37 Mercurial. These are installed in various Docker images.
  38
  39 To upgrade Mercurial, typically you just need to update the source URL
  40 and its hash in this file.
  41
  42 Non-Debian Linux Docker Images
  43 ------------------------------
  44
  45 The ``taskcluster/docker/recipes/install-mercurial.sh`` script is sourced
  46 by a handful of Docker images to install Mercurial.
  47
  48 The script references 3 tooltool artifacts:
  49
  50 * A Mercurial source tarball (for ``pip`` installs).
  51 * A ``mercurial_*_amd64.deb`` Debian package.
  52 * A ``mercurial-common_*_all.deb`` Debian package.
  53
  54 The source tarball is a vanilla Mercurial source distribution. The Debian
  55 archives will need to be produced manually.
  56
  57 To produce the Debian archives,
  58 ``hg clone https://www.mercurial-scm.org/repo/hg`` and ``hg update`` to
  59 the tag being built. Then run ``make docker-ubuntu-xenial``. This will
  60 build the Mercurial Debian packages in a Docker container. It will deposit
  61 the produced packages in ``packages/ubuntu-xenial/``.
  62
  63 Once all 3 files are available, copy them to the same directory and
  64 upload them to tooltool.
  65
  66    $ tooltool.py add --public mercurial-x.y.z.tar.gz mercurial*.deb
  67    $ tooltool.py upload --message 'Bug XXX - Mercurial x.y.z' --authentication-file ~/.tooltoolauth
  68
  69 .. note::
  70
  71    See https://wiki.mozilla.org/ReleaseEngineering/Applications/Tooltool#How_To_Upload_To_Tooltool
  72    for how to use tooltool and where to obtain ``tooltool.py``.
  73
  74 Next, copy values from the ``manifest.tt`` file into
  75 ``taskcluster/docker/recipes/install-mercurial.sh``. See revision
  76 ``977768c296ca`` for an example upgrade.
  77
  78 Windows AMIs
  79 ------------
  80
  81 https://github.com/mozilla-releng/OpenCloudConfig defines the Windows
  82 environment for various Windows AMIs used by Taskcluster. Several of
  83 the files reference a ``mercurial-x.y.z-*.msi`` installer. These references
  84 will need to be updated to the Mercurial version being upgraded to.
  85
  86 The ``robustcheckout`` extension is also vendored into this repository
  87 at ``userdata/Configuration/FirefoxBuildResources/robustcheckout.py``. It
  88 should also be updated if needed.
  89
  90 Puppet Maintained Hosts
  91 -----------------------
  92
  93 Some hosts (namely macOS machines) are managed by Puppet and Puppet is used
  94 to install Mercurial.
  95
  96 Puppet code lives in the https://hg.mozilla.org/build/puppet repository.
  97 Relevant files are in ``modules/mercurial/``,
  98 ``modules/packages/manifests/mozilla/mozilla-python27-mercurial-debian/``,
  99 and ``modules/packages/manifests/mozilla/py27_mercurial*``. A copy of
 100 ``robustcheckout`` is also vendored at
 101 ``modules/mercurial/files/robustcheckout.py``.
 102
 103 .. note::
 104
 105    The steps to upgrade Mercurial in Puppet aren't currently captured here.
 106    Someone should capture those...