docs/distribution-job-builds.rst

   1 Distribution Job Builds
   2 =======================
   3
   4 Unlike autorelease builds, which build every project from source, distribution
   5 jobs only build a few Karaf features. The other artifacts are pulled pre-built
   6 from OpenDaylight's Nexus repository and packaged into the Karaf distribution.
   7 This makes them much quicker (minutes instead of ~4 hours).
   8
   9 The other major difference between autorelease and distribution job builds is
  10 that distribution jobs use the -SNAPSHOT artifact version suffixes that are
  11 actually stored in version control, whereas autorelease builds rewrite versions
  12 to use the suffix for the next release, like -Carbon-SR1 or -Nitrogen. Because
  13 of this, distribution builds are sometimes called "snapshot builds".
  14
  15 For each active branch, builds created by distribution jobs can be found in the
  16 subdirectories at `opendaylight.snapshot/org/opendaylight/integration
  17 /distribution-karaf/`_. Each build artifact is versioned with a timestamp and
  18 unique, incrementing build number.
  19
  20 Distribution Builds Triggered by Merge Jobs
  21 -------------------------------------------
  22
  23 Distribution job builds are typically kicked off when a patch is merged into
  24 a project. Projects define `<project>`-merge-<branch> Jenkins jobs, which are
  25 kicked off by Gerrit merge event. To find the merge job for a Gerrit, look
  26 for comments from the jenkins-releng user like "Build Started
  27 https://jenkins.opendaylight.org/releng/job/netvirt-merge-boron/216/".
  28
  29 Alternatively, browse a project's Jenkins tab and look at the recent runs.
  30 For example, go to https://jenkins.opendaylight.org/releng/, select
  31 Merge-Carbon and you'll find the list of all project merge jobs in the format
  32 `<project>`-merge-carbon. Click any to view the recent build job details and
  33 logs.
  34
  35 Custom Distributions
  36 --------------------
  37
  38 Distributions can be built with an additional set of unmerged patches. The
  39 `integration-multipatch-test-<branch>`_ jobs allow users to specify a set of
  40 patches to cherry-pick onto a project's source code before building. This is
  41 very useful for testing complex changes that impact multiple projects.
  42
  43 To build a custom distribution that includes a set of unmerged patches, first
  44 make sure you have permission to trigger Jenkins jobs. Send an email to the
  45 OpenDaylight Helpdesk (helpdesk@opendaylight.org) to request access. Be sure
  46 to include your Linux Foundation user ID in the request.
  47
  48 Once you can trigger Jenkins jobs, navigate to the Jenkins web UI for the
  49 multipatch-test job of the branch you're interested in. Make sure you're
  50 logged in, then click on the "Build with Parameters" link in the sidebar.
  51 The only parameter that requires configuration is PATCHES_TO_BUILD. This is
  52 a CSV list of patches in project[=checkout][:cherry-pick]* format. For each
  53 given project, the job will checkout 0 or 1 specified patches, then cherry-pick
  54 0 or more additional patches on top of that checkout. If no checkout is
  55 specified, cherry-picks will be done on top of the tip of the branch of the
  56 multipatch-test job you're using.
  57
  58 For example, to build with a single unmerged patch from NetVirt:
  59
  60     netvirt:59/50259/47
  61
  62 Because of the colon, this would cherry-pick the change on top of the tip
  63 of the multipatch-test job branch.
  64
  65 To build with the same NetVirt patch, but by directly checking it out, use
  66 an equals sign.
  67
  68     netvirt=59/50259/47
  69
  70 This will be the same thing if the patch has recently been rebased on top
  71 of the tip of the branch, but may be different if the patch is based on a
  72 different set of patches.
  73
  74 To build with checked-out patches from Genius and NetVirt:
  75
  76     genius=32/53632/9,netvirt=59/50259/47
  77
  78 To checkout a patch from controller, then cherry-pick another on top of it:
  79
  80     controller=61/29761/5:45/29645/6
  81
  82 The numbers in the changeset are the Gerrit change ID of the patch (middle
  83 number) and the patchset of the Gerrit (last number). The first number is
  84 just the last two digits of the Gerrit change ID (I'm not sure why this is
  85 necessary). I belive it's required that patches be listed in the order the
  86 projects are built (NetVirt depends on Genius, so Genius is listed first).
  87
  88 For the definitive explination of how the multipatch job works, see the `JJB
  89 source that defines it`_.
  90
  91 .. _opendaylight.snapshot/org/opendaylight/integration /distribution-karaf/: https://nexus.opendaylight.org/content/repositories/opendaylight.snapshot/org/opendaylight/integration/distribution-karaf/
  92 .. _integration-multipatch-test-<branch>: https://jenkins.opendaylight.org/releng/search/?q=integration-multipatch-test
  93 .. _JJB source that defines it: https://github.com/opendaylight/releng-builder/blob/master/jjb/integration/include-raw-integration-multipatch-distribution-test.sh