Bileto

Revision 14 as of 2014-10-09 11:55:47

Clear message

Landing changes through the CI Train

PLEASE NOTE: This document is still being worked on!

Landing your change to Ubuntu

This part might be well known to most landers that already performed landings through CI Train.

The train provides two possibilities - you can either land your changes into the archive through listing merge proposals that you want to release or by source packages directly. The first approach is recommended.

Whenever you want to request a release of your component to the archive:

  • If you are new to this process, ask a trainguard in #ubuntu-ci-eng to give you the required permissions for operating the CI Train.
  • Open the CI Train spreadsheet https://wiki.ubuntu.com/citrain.

  • On the main 'Pending' sheet add a new row to the list, filling out the required fields as they go.
    • Description of landing: write here an overview of what your landing is about - is it fixing bugs? Adding some features? Try being informative without being over-verbose.
    • Lander: your irc nick-name and/or of other people that will also drive the landing (space separated)
    • Comments: used for any additional comments and offline discussion with the Landing Team.
    • Test plans to run: each project handled by CI Train needs to have a test plan, best in form of a wiki page or other document, that overviews of how you, the lander, intend to test the given component. See #QA for more details.

    • Merge proposals to land: here you list all the links to the merge proposals you want to land in this landing. Please note we need a space separated list of MP links, not branch links. More on this later.

    • Additional source packages to land: here you list the 'additional' source packages that you would like to upload to the silo PPA besides what is already handled by MPs. Can be used for projects that Ubuntu is not upstream for or which have no bzr trunk.
    • Target distribution: select which distribution and series you want to land into.
    • QA sign off needed?: usually this should be left blank, but the rule is: in normal operation, utopic silos do not need QA sign-off while ubuntu-rtm/14.09 landings by default require it. See #QA for more information.

    • Ready for a silo?: change this to 'Yes' once you think this landing is ready to get a silo assigned. Before this is done, the Landing Team will not allocate a silo.
  • Once the landing row in the spreadsheet is filled and the 'Ready for a silo?' field is set to Yes, wait for a trainguard to assign you a silo.
    • Sometimes it might be useful to ping a trainguard directly on #ubuntu-ci-eng
  • After you have a silo allocated, it will appear on the CI Train Dashboard.

  • Use the 'Build' button above your landing card in the dashboard to start building packages from the specified merge requests.
    • If you have added some 'Additional source packages to land', you need to provide a trainguard or core-dev with the required source package so that they can upload those to your silo.
  • After the packages finish building, it is now the landers responsibility to test the packages from the PPA on a real device. More information about it on the #QA section - but remember: do not only test if the fix works, test if your change didn't break anything else. Use the Test Plan.

  • If your packages pass your testing criteria, mark the silo as tested:
    • Find your landing row on the CI Train Spreadsheet again.

    • Go to the 'Testing pass?' column.
    • Set it to the following: Yes (<image_number> <device_name> <person_that_tested>), e.g. 'Yes (#88 krillin sil2100).

  • In case your silo needs QA sign-off, wait for the QA Team to finish testing on the silo. This will be indicated in the spreadsheet and the dashboard.
  • The landing team will now publish the silo to the archive if everything is OK packaging-wise.
  • Last final step: once all packages migrate to the archive, you (or someone from the Landing Team) need to Merge & Clean the silo. This can be done by the 'Clean' button in the CI Train Dashboard above your landing.

This is the standard process. When you prepare a list of MPs to land and provide them to CI Train, the infrastructure will merge all of them together and build a source package using bzr bd. This package is then uploaded to the silo PPA that has been assigned to your landing. CI Train also automatically generates the debian/changelog for you using the MPs commit-messages. Every landing creates a new version in the changelog with one entry per merge. The version number is also auto-generated every time. After all changes land into the archive, during the 'Merge & Clean' state these all merges are finally merged into trunk.

So, the general steps in the landing process from the landers perspective are:

  1. Fill in a landing request
  2. Wait for silo assignment
  3. Build packages in silo PPA
  4. Test packages from the silo PPA on real hardware
  5. Mark silo as tested
  6. (in some cases) Wait for silo to be QA signed-off
  7. Wait for silo to be published
  8. Clean the silo

Handling landings to ubuntu and ubuntu-rtm

Since the ubuntu-rtm distribution has been opened, we are providing services enabling landing package versions to both utopic and 14.09. The current policy enforces that everything that lands to 14.09 is required to land in utopic as well, with a recommendation of landing to utopic first.

The multiple ways of landing things to ubuntu-rtm is explained in the citrain/RTMLandingApproaches wiki page. But the general principle is that every ubuntu landing (if not mentioned differently) gets a sync silo assigned for ubuntu-rtm.

QA Sign-off Needed

Under certain circumstances your landing may need to go through QA sign off. This is usually during situations when the quality level of the image has regressed severely or must be maintained at a high-level. Right now these are:

  • During TRAINCON-0
  • For all landings to the ubuntu-rtm branch

There is an exception to this rule if your landing contains an isolated bug fix. Right now there is not a strict definition of this term, but as guidance an isolated bug fix landing should contain:

  • One, or only a couple of bug fixes
  • The change should be small and not impacting a large number of sub-components of that package
  • The package itself should not have a lot of reverse dependencies, since this makes it much harder to assess the impact of the landing.

If QA sign off is required then you will be expected to provide more detailed information about the testing you have done in the Test plans to run column of the landing spreadsheet so that QA have a good basis on which to build their additional testing. Here are some tips:

  • Never just test that the bug(s) alone are fixed - remember the potential for regressions
  • Look at what is actually landing and make sure testing is done for all the updated packages. For example if the primary intent of the silo is to fix music player controls, but the fix requires a media-hub update then you should probably run the whole media-hub test plan.
  • Take into consideration the dependencies and reverse dependencies involved - ask yourself, who could I break? Ideally your packages test plan should have some guidance on this (for example see the Dependents/Clients section media-hub's test plan

  • If you only provide a link to the test plan, then bear in mind that QA will assume you've run all the tests in that plan and they have passed. If tests then fail for a reason you haven't mentioned then it will cause confusion and delay the landing, so make sure to record all cases where you have not run a test or a test has failed (and why).

Lastly, if you don't use the citrain tool for installing the silo then you need to mention what steps you used to install the silo, since citrain is the assumed way.

Isolated bugfixes for ubuntu-rtm - confirmation

Whenever a landing is targeting ubuntu-rtm and is marked by the lander as not requiring QA sign-off because of an isolated bugfix, the Landing Team tries to verify if this indeed falls into this category. The Landing Team either by themselves or with the help of the QA team look at the landing description, looking for any rationale for this exception. Merge requests or diffs are also examined in case that's needed.

The best practice is to directly ping the QA team with a question if your change can go through without a full QA sign-off. The QA Team is here to ensure that things landing into ubuntu-rtm are as safe as possible.