libcxx/docs/AddingNewCIJobs.rst

   1 .. _AddingNewCIJobs:
   2
   3 ==================
   4 Adding New CI Jobs
   5 ==================
   6
   7 .. contents::
   8   :local:
   9
  10 Adding The Job
  11 ==============
  12
  13 libc++ uses Buildkite for running its CI. Setting up new CI jobs is easy, and
  14 these jobs can run either on our existing infrastructure, or on your own.
  15
  16 If you need to run the job on your own machines, please follow the
  17 `Buildkite guide <https://buildkite.com/docs/agent/v3>`_ to setup your
  18 own agents. Make sure you tag your agents in a way that you'll be able
  19 to recognize them when defining your job below. Finally, in order for the
  20 agent to register itself to Buildkite, it will need a BuildKite Agent token.
  21 Please contact a maintainer to get your token.
  22
  23 Then, simply add a job to the Buildkite pipeline by editing ``libcxx/utils/ci/buildkite-pipeline.yml``.
  24 Take a look at how the surrounding jobs are defined and do something similar.
  25 An example of a job definition is:
  26
  27 .. code-block:: yaml
  28
  29   - label: "C++11"
  30     command: "libcxx/utils/ci/run-buildbot generic-cxx11"
  31     artifact_paths:
  32       - "**/test-results.xml"
  33     agents:
  34       queue: "libcxx-builders"
  35       os: "linux"
  36     retry:
  37       [...]
  38
  39 If you create your own agents, put them in the ``libcxx-builders`` queue and
  40 use agent tags to allow targeting your agents from the Buildkite pipeline
  41 config appropriately.
  42
  43 We try to keep the pipeline definition file as simple as possible, and to
  44 keep any script used for CI inside ``libcxx/utils/ci``. This ensures that
  45 it's possible to reproduce CI issues locally with ease, understanding of
  46 course that some setups may require access to special hardware that is not
  47 available.
  48
  49 Finally, add your contact info to ``libcxx/utils/ci/BOT_OWNERS.txt``. This will
  50 be used to contact you when there are issues with the bot.
  51
  52 Testing Your New Job
  53 ====================
  54
  55 Testing your new job is easy -- once your agent is set up (if any), just open
  56 a code review and the libc++ CI pipeline will run, including any changes you
  57 might have made to the pipeline definition itself.
  58
  59 Service Level Agreement
  60 =======================
  61
  62 To keep the libc++ CI useful for everyone, we aim for a quick turnaround time
  63 for all CI jobs. This allows the overall pipeline to finish in a reasonable
  64 amount of time, which is important because it directly affects our development
  65 velocity. We also try to make sure that jobs run on reliable infrastructure in
  66 order to avoid flaky failures, which reduce the value of CI for everyone.
  67
  68 We may be reluctant to add and support CI jobs that take a long time to finish
  69 or that are too flaky.