« back to all changes in this revision
Viewing changes to docs/introduction.rst
- browse files at revision 114
- compare with another revision
- download diff
- download tarball
- view history from revision 114
- Committer: Tarmac
- Author(s): mrazik
- Date: 2013-06-14 15:25:58 UTC
- mfrom: (97.5.12 docs)
- Revision ID: tarmac-20130614152558-6oti7qnqhsjuq433
Adding sphinx documentation.
Approved by PS Jenkins bot, Francis Ginther.
Approved by PS Jenkins bot, Francis Ginther.
- files added:
- debian/jenkins-launchpad-plugin.docs
- docs
- docs/_build
- docs/_static
- docs/_templates
- docs/images
- files modified:
- README
added
removed
docs/introduction.rst
1
jenkins-launchpad-plugin is a set of scripts for polling launchpad (looking
2
for new merge proposals) and for updating launchpad merge proposals with
3
different messages and votes.
4
5
..
6
Requirements
7
============
8
https://wiki.jenkins-ci.org/display/JENKINS/Parameterized+Trigger+Plugin
9
10
11
Python Scripts
12
==============
13
The main scripts are:
14
* ``bin/launchpadTrigger`` - This is the main polling scripts. It looks for
15
a specific merge proposals (e.g. "Needs review" or "Approved") of a given
16
target branch (e.g. lp:unity) and starts a given jenkins job. The
17
responsibilities of this script end with starting the job.
18
* ``bin/voteOnMergeProposal`` - This script adds a vote to a given merge
19
proposal together with links to all relevant jenkins jobs that were
20
executed. This is usually used for merge proposals which are in "Needs
21
review" and no further action is needed (such as merging the code)
22
* ``bin/autoland`` - Takes care of the actual merge and possibly dputs to
23
(one or many) PPA. This script is usually used for merge proposals in
24
"Approved" state.
25
* ``bin/dput`` - Helper script for dputing into PPA.
26
27
28
How it works with jenkins
29
=========================
30
31
Step 1 - Jenkins job doing the actual testing
32
---------------------------------------------
33
The first step is to create a jenkins job where you want to do your
34
testing. Multiconfiguration (aka Matrix) jobs are supported as well as
35
unlimited depth of downstream jobs. Results from all are posted to the
36
merge proposal (with some filtering possible).
37
38
In order to use the launchpadTrigger script the job needs to accept the
39
following string parameters which are both automatically set by
40
launchpadTrigger at the time of triggering:
41
* merge_proposal - URL of the merge proposal
42
* candidate_revision - revision of the branch that is being tested
43
(this is to make sure we are consistent in what we test)
44
45
This is how it looks in jenkins:
46
47
.. image:: images/job_params.png
48
49
We usually have two jobs per project. One called $project-ci (triggered
50
whenever a new merge proposal is created) and one called $project-autoland
51
which is triggered when a merge proposal is Approved. They primarily differ
52
in the post build action. While the jenkins bot only votes (Needs
53
Fixing/Approved) for merge proposals in 'Needs review' it votes _and_
54
merges the code for proposals in 'Approved'.
55
56
Step 2 - Triggering the jenkins job
57
-----------------------------------
58
Once we have a jenkins job we need to trigger it. There are at least two
59
options.
60
61
jenkins ScriptTrigger plugin
62
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
63
64
In the triggering section you can run something like::
65
66
launchpadTrigger --job=$YOUR_JOB --branch=lp:$YOUR_PROJECT --trigger-ci
67
68
This is how it looks in jenkins:
69
70
.. image:: images/scripttrigger.png
71
72
With the script above your job will be started whenever there is a
73
new merge proposal in 'Needs review' state.
74
If you want to start the testing for 'Approved' merge proposals you
75
can use ``--autoland`` instead of ``--trigger-ci``.
76
77
Using the ScriptTrigger plugin is however not recommended as there
78
are scalability issues. Once you have a lot of projects it is hard to
79
debug issues and it behaves weirdly. It is, however, not an issue for
80
a small amount of projects (lets say ~10).
81
82
83
custom jenkins (cron) job
84
^^^^^^^^^^^^^^^^^^^^^^^^^
85
We are currently using a custom job called trigger-ci-and-autolanding. This
86
job is triggered by timer (every 15 minutes), reads the configuration from
87
lp:cupstream2distro-config (this config essentially defines the YOUR_JOB <->
88
YOUR_PROJECT pairing) and polls all the jobs from the config.
89
90
91
Step 3 - job is finished, what now?
92
-----------------------------------
93
After your testing job is finished we want to update the merge proposal or
94
merge the code (or whatever you want). For that purpose we are using couple
95
of custom jobs which are executed from a post-build section of your jenkins
96
job (see Step 1):
97
98
generic-update_mp
99
^^^^^^^^^^^^^^^^^
100
This job executes the voteOnMergeProposal script and you need the pass some
101
info from $YOUR_JOB to this via parameters (see the screenshot below). You
102
need to trigger generic-update_mp with different parameters depending on
103
the result of your job. Fortunately the jenkins "Parameterized Trigger Plugin" can help here.
104
105
.. image:: images/generic-update_mp_trigger.png
106
107
Build section of generic-update_mp might look like this:
108
109
.. image:: images/generic-update_mp_build.png
110
111
112
generic-land
113
^^^^^^^^^^^^
114
This job is executed when you want to merge the code rather than just to vote.
115
There are again few options how to configure it.
116
117
In case $YOUR_JOB is a multiconfiguration job then the landing can't happen
118
in the build step as you would be trying to merge several times (one time
119
per configuration). You need to use post-build section in a way similar to
120
generic-update_mp:
121
122
.. image:: images/generic-update_mp_trigger.png
123
124
As the ``autoland`` script takes more arguments the ``voteOnMergeProposal``
125
you might want to pass more variables here. See ``autoland --help`` for
126
more information on supported options.
127
128
129
Examples
130
--------
131
lp:unity/phablet
132
^^^^^^^^^^^^^^^^
133
The following example is a real vote on a merge proposal for
134
lp:unity/phablet.
135
136
There is a following job structure:
137
138
* ``unity-phablet-ci`` - the "master" ci job triggered whenever a new jenkins merge proposal is created. This job triggers the following jobs:
139
140
* ``unity-phablet-qmluitests`` - this job is not configured to be published
141
on jenkins.qa.ubuntu.com and therefore the internal IP is mangled to
142
s-jenkins (see ``settings.py``)
143
* ``unity-phablet-[quantal|raring]-[armhf|i386]-ci`` - jobs building on
144
quantal and raring and armhf and i386. The armhf jobs are configured to
145
archive the resulting deb files for future use and therefore a link to
146
that deb is printed too.
147
* ``generic-mediumtests-runner`` - job that is running autopilot (UI tests)
148
149
In total there are 6 different jenkins jobs with tests + 1 master which
150
controls them all and then executes the ``generic-update_mp`` job.
151
152
The downstream jobs might be whatever you like. For some projects we have
153
e.g. clang builds.
154
155
Even though ``generic-update_mp`` is downstream to unity-phablet-ci it is
156
filtered from the message (see ``settings.py``) as well as few other
157
intermediate jobs.
158
159
.. image:: images/mp_example.png
Loggerhead is a web-based interface for Breezy
Version: 2.0.1