FAQ
This page is part of the daily release process documentation
The FAQ is divided in multiple sequences depending on your role in the development of ubuntu, with the hope that you will be able to find what you are looking for quicker this way. If you have any question that isn't addressed below, please ping didrocks on IRC freenode (#ubuntu-unity) and I'll complete this page.
Upstream developers
What's needed to be done when proposing a branch or reviewing?
As discussed in DailyRelease/UpstreamMerge#The_merge_procedure, when proposing a branch or reviewing a peer's work, multiple rules have been established. The developers needs to:
- Design needs to acknowledge the change if there is any visual change involved
Both the developer, reviewer and the integration team ensure that ubuntu processes are followed (UI Freeze/Feature Freeze for instance). If exceptions are required, they check before approving for merging that they are acknowledged by different parts. The integration team can help smooth to have this happened, but the requests should emerge from developers.
- Relevant bugs are attached to the merge proposal. This is useful for tracking what changed and for generating the changelog as we'll see in the next part
- Review of new/modified tests (for existence)
- They ensure that it builds and unit tests are passing [automated]
- Another important one, especially when you refactor, is to ensure that integration tests are still passing
- Review of the change itself by another peer contributor
- If the change seems important enough to have a bug report linked, ensure that the merge request is linked to a bug report (and you will get all the praise in debian/changelog as well!)
- If packaging changes are needed, ping the integration team so that they acknowledge them and ensure the packaging changes are part of the merge proposal.
When you approve a change, do not forget to check that there is a commit message in launchpad provided and to set the global status to "approved".
When do changes need to land in a coherent piece?
Some changes can happen and touch various components (even across different stacks). To avoid loosing a daily release because only half of transition landed in some upstream projects (and so, tests will fail because they catch this issues, isn't it? ;)), it's asked to ensure that all transitions are merged by 00 UTC. Then, you can start approving again transition starting from 06 UTC. We can try to make this window shorter in the future, but let's see first how this work in practice. For any big transition, please coordinate with the ubuntu-unity team team so that they can give a hand.
I have a change involving packaging modifications
As told in a previous section, just ask for the ubuntu-unity team to do some review or assisting in doing those changes.
I want to build the package locally myself
If you have done some packaging changes, or added a C symbol, you maybe want to ensure that it's building fine. Quite simple, just go into your branch directory and run $ bzr bd (from the bzr-builddeb package). This will build your package on your machine using the same flags and checks than on the builders. No need to autoreconf if you are using autotools, everything is handled for you. You will get warned as well if some installed files are missing.
I need to break an API/ABI
The first question is: "are you sure?". Remember that API changes are a PITA for all third parties, in particular if your API is public. Retro-compatibility is key. And yes, your dbus interface should be considered as part of your API!
If you still want to do that, ensure that you bump your soname if the ABI is broken, then, multiple packaging changes are needed. Consequently, ensure to ping your lovely ubuntu-unity team to request assistance. The transition should happen (if no retrocompatibility is provided) within the previously mentionned timeframe to have everything landing in coherence.
Also, please do think to bump the version in debian/changelog as well (this will be for next release). If there is already an UNRELEASED content, change it from
0.42.1+13.10.20130815-0ubuntu1 (or 0.42.1-0ubuntu1)
to:
0.42.2-0ubuntu1 for instance (you don't need to strip the +<series_version> part, if you do, the daily release will readd it at next successful release)
Or run $ dch and change the version to match this (ensure you have UNRELEASED content and not "raring" or any version in the first line). Add a Breaks: in one of the binary of the next version of B rebuild against A: Breaks B (<< newversion of B which was rebuilt against A)
Finally, follow for all reverse dependencies the following sections about packaging B needing to be rebuilt against an ABI breakage in A.
I'm exposing a new C/C++ symbols in my library, it seems that some packaging changes are needed…
Exported symbols track library's API/ABI to some extend. Adding new symbols is ok, changing symbols, whilst exporting both old & new as versioned symbols is also ok, removing symbols breaks the API or changing non-versioned symbols breaks the API/ABI thus requiring a soname change (libraryN package rename to libraryM).
Here is a good overview of some things one should do to maintain a stable API/ABI (a bit C++ centric, but still good): http://techbase.kde.org/Policies/Binary_Compatibility_Issues_With_C++
Debian packages have a debian/<packagename>.symbols file which lists all exposed symbols from your library (for C++ one also needs to use demangled names). When you try to build the package containing a new symbol, you will see something like:
--- debian/libdee-1.0-4.symbols (libdee-1.0-4_1.0.14-0ubuntu2_amd64) +++ dpkg-gensymbolsvPEBau 2013-02-05 09:43:28.529715528 +0100 @@ -4,6 +4,7 @@ dee_analyzer_collate_cmp@Base 0.5.22-1ubuntu1 dee_analyzer_collate_cmp_func@Base 0.5.22-1ubuntu1 dee_analyzer_collate_key@Base 0.5.22-1ubuntu1 + dee_analyzer_get_type@Base 1.0.14-0ubuntu2 dee_analyzer_new@Base 0.5.22-1ubuntu1 dee_analyzer_tokenize@Base 0.5.22-1ubuntu1 dee_client_get_type@Base 1.0.0
The diff shows that debian/libdee-1.0-4.symbols doesn't list the exposed dee_analyzer_get_type new symbol. You see a version number next to it, corresponding to the current package version. The issue is that you don't know what will be the package version in the future when the next daily release will happen (even if you can infer), what to put then?
The answer is easier than you might think. As explained in the corresponding section, the daily release bot will know what version is needed, so you just need to give a hint that the new symbol is there for the upstream merger to pass.
For than, just include the symbol, with 0replaceme (0replacemepleasepleaseplease or anything else appended to 0replaceme is accepted as well if you feel adventurous ;)) as the version for the branch you will propose as a merge request. You will thus set in your symbols file:
dee_analyzer_collate_cmp@Base 0.5.22-1ubuntu1 dee_analyzer_collate_cmp_func@Base 0.5.22-1ubuntu1 dee_analyzer_collate_key@Base 0.5.22-1ubuntu1 dee_analyzer_get_type@Base 0replaceme dee_analyzer_new@Base 0.5.22-1ubuntu1 dee_analyzer_tokenize@Base 0.5.22-1ubuntu1 dee_client_get_type@Base 1.0.0
The dee_analyzer_get_type@Base 0replaceme line will be replace with the exact version we release in the next daily release.
Look at the diff, if there is any MISSING symbols, in means that you may have broken the ABI by removing some available symbols to your consumers, please check the section about ABI breakage in this page before going further.
NB! For C++ the diff will be using mangled symbol names, but if you pipe the diff through C++filt, you can get the demangled name. For example if the diff has a clearly C++ symbol like this one:
$ cat foo.patch --- debian/qtubuntu-sensors.symbols (qtubuntu-sensors_0.5.1+13.10.20130412ubuntu.unity.next-0ubuntu1_amd64) +++ dpkg-gensymbolsqRtu3z 2013-05-24 10:23:38.081786917 +0100 @@ -16,6 +16,13 @@ (c++)"OrientationSensorReading::qt_metacall(QMetaObject::Call, int, void**)@Base" 0.5.1 (c++)"OrientationSensorReading::qt_metacast(char const*)@Base" 0.5.1 (c++)"OrientationSensorReading::staticMetaObject@Base" 0.5.1 + _ZN24OrientationSensorReadingC1EP7QObject@Base 0.5.1+13.10.20130412ubuntu.unity.next-0ubuntu1 + _ZN24OrientationSensorReadingC2EP7QObject@Base 0.5.1+13.10.20130412ubuntu.unity.next-0ubuntu1 + _ZN24OrientationSensorReadingD0Ev@Base 0.5.1+13.10.20130412ubuntu.unity.next-0ubuntu1 + _ZN24OrientationSensorReadingD1Ev@Base 0.5.1+13.10.20130412ubuntu.unity.next-0ubuntu1 + _ZN24OrientationSensorReadingD2Ev@Base 0.5.1+13.10.20130412ubuntu.unity.next-0ubuntu1 + _ZN26AccelerometerSensorReading11qt_metacallEN11QMetaObject4CallEiPPv@Base 0.5.1+13.10.20130412ubuntu.unity.next-0ubuntu1 + _ZN26AccelerometerSensorReading11qt_metacastEPKc@Base 0.5.1+13.10.20130412ubuntu.unity.next-0ubuntu1 (c++)"typeinfo for AccelerometerSensorReading@Base" 0.5.1 (c++)"typeinfo for OrientationSensor@Base" 0.5.1 (c++)"typeinfo for OrientationSensorReading@Base" 0.5.1
What you need is:
redirect the diff in a file, replace any new values with 0replaceme, and unmangles the symbols for c++filt. In your build source directory (if you used bzr bd, it's ../build-area/<source_name>-<version>, relative to your trunk:
fakeroot dh_makeshlibs | sed -e 's/^\+ \(.*\) \(.*\)/\+ \1 0replaceme/' -e 's/\([+-]\) \(_.*\) \(.*\)/\1 (c++)"\2" \3/' | c++filt > /tmp/diff_for_symbols
What you will get is something like:
--- debian/qtubuntu-sensors.symbols (qtubuntu-sensors_0.5.1+13.10.20130412ubuntu.unity.next-0ubuntu1_amd64) +++ dpkg-gensymbolsqRtu3z 2013-05-24 10:23:38.081786917 +0100 @@ -16,6 +16,13 @@ (c++)"OrientationSensorReading::qt_metacall(QMetaObject::Call, int, void**)@Base" 0.5.1 (c++)"OrientationSensorReading::qt_metacast(char const*)@Base" 0.5.1 (c++)"OrientationSensorReading::staticMetaObject@Base" 0.5.1 + (c++)"OrientationSensorReading::OrientationSensorReading(QObject*)@Base" 0.5.1+13.10.20130412ubuntu.unity.next-0ubuntu1 + (c++)"OrientationSensorReading::OrientationSensorReading(QObject*)@Base" 0.5.1+13.10.20130412ubuntu.unity.next-0ubuntu1 + (c++)"OrientationSensorReading::~OrientationSensorReading()@Base" 0.5.1+13.10.20130412ubuntu.unity.next-0ubuntu1 + (c++)"OrientationSensorReading::~OrientationSensorReading()@Base" 0.5.1+13.10.20130412ubuntu.unity.next-0ubuntu1 + (c++)"OrientationSensorReading::~OrientationSensorReading()@Base" 0.5.1+13.10.20130412ubuntu.unity.next-0ubuntu1 + (c++)"AccelerometerSensorReading::qt_metacall(QMetaObject::Call, int, void**)@Base" 0.5.1+13.10.20130412ubuntu.unity.next-0ubuntu1 + (c++)"AccelerometerSensorReading::qt_metacast(char const*)@Base" 0.5.1+13.10.20130412ubuntu.unity.next-0ubuntu1 (c++)"typeinfo for AccelerometerSensorReading@Base" 0.5.1 (c++)"typeinfo for OrientationSensor@Base" 0.5.1 (c++)"typeinfo for OrientationSensorReading@Base" 0.5.1
- Opens the file, if there is any MISSING symbols, in means that you may have broken the ABI by removing some available symbols to your consumers, please check the section about ABI breakage in this page before going further. If you are sure it's what you need to do (and checked the above doc), remove all - and #MISSING content in the symbols diff file (/tmp/diff_for_symbols).
- Once, check, apply the diff to your new symbols file:
cd <source_of_your_branch>; patch -p0 < /tmp/diff_for_symbols
- And commit this!
Also, please do think to bump the version in debian/changelog as well (this will be for next release). If there is already an UNRELEASED content, change it from
0.42.1+13.10.20130815-0ubuntu1 (or 0.42.1-0ubuntu1)
to:
0.42.2-0ubuntu1 for instance (you don't need to strip the +<series_version> part, if you do, the daily release will readd it at next successful release)
Or run $ dch and change the version to match this (ensure you have UNRELEASED content and not "raring" or any version in the first line).
Finally, follow for all reverse dependencies the following sections about packaging B depending on a new symbol you just added on A.
Further information on debian package symbols files can be found at:
My package B depends on a new symbol I just added on A or needs to be rebuilt against an ABI breakage in A
As you bumped the version in debian/changelog for the previous package, this is going to be easy.
Normally, you should have, in package B (debian/control)
Build-depends: <…> A (>= 0.42)
Just bump the version to the one you just added for A (normally without the -0ubuntu1). So, let's see you added a new symbol in 0.42.2-0ubuntu1:
Build-depends: <…> A (>= 0.42.2)
And propose that along with your change to depends on the new feature.
Think as well that for interpreted languages, you have runtime dependencies on the binary package. Imagine a new feature added on autopilot and the changelog has been bumped to 0.43:
So that unity depens at *runtime* (only for interpreted languages) on the right autopilot package:
Package: unity-autopilot Depends: autopilot (>= 0.43)
Always think about dependencies when changing your code!
I want one of my commit not being part of debian/changelog
If you are making a trivial change and don't want your typo fix to be listed, you can set "#nochangelog" into your commit message while merging to trunk and it will get ignored.
I have a big change that needs to be mention explicitely in debian/changelog, and I don't think the commit message is meaningful enough
If you file manually the changelog message in debian/changelog, the daily release will keep your original message and ignore the commit message. Take care that it won't pick bugs linked to that merge as well.
You need then mention it manually in debian/changelog: $ dch
-> edit the change and save.
This is creating an UNRELEASED entry for you. Check that you don't have "raring" but UNRELEASED in the first line (make the change yourself before saving if it's not the case).
This means that you do not have to care about the version in the changelog, as long as you're creating a new entry when you need to. The daily release machinery will update the version to be correct when it makes the next release.
I'm bumping the upstream version, what should I do?
This section applies to you if you want to update the upstream part of the version - that's the part before the '+<series_version>'. You might want to do this if you're starting a new development series, for example if you're moving from version 1.7 to 1.8.
How you do this depends if your version is released or not.
If you bump from 1.7 to 1.8 and it's released, then to edit debian/changelog:
dch -v 1.8-0ubuntu1
If you bump from 1.7 to 1.8, but it's not released (just a pre-release bump)
dch -v 1.8~-0ubuntu1
I want to have a daily release kicked in now
Daily release are happening starting at 2AM UTC. So we shouldn't restart any stack at this time until the builds finishes (around 9AM UTC) as the build-deps order can interleave inconsistencies between stack.
For the rest, you have the Ubuntu Unity team which can triggers a build if needed. We have people in European and US timezone being able to relaunch the jobs (more info on the directory).
If you have a really urgent fix to upload with ubuntu maintainers handy, you can have a look at next section.
Ubuntu Maintainers
I want to upload a change to a package under daily release process
Multiple possibilities there.
The change itself can wait next daily release
If it's an upstream change, we strongly advise you to follow the same procedure and rules than the upstream developers, meaning, proposing a merge request and so on… bzr lp-propose and bzr branch lp:<source_package_name> are regularly and automatically adjusted as part of the daily release process to point to the right branches so that you can find them easily. Vcs-Bzr in debian/control should point to the right location as well.
Then, just refer to the upstream merging guidelines above. Once approved, this change will be in the next daily release (if tests pass).
An urgent change is needed
If the change needs to be done right away, but can wait for a full testing round (~2 hours), you can:
- Propose your merge request
Ping someone from the ubuntu-unity team who will ensure the branch is reviewing in priority and rerun a daily release manually including your change. That way, your change will get the same quality reviews and tests checking than anything else entering the distro.
It's really urgent
You can upload right away your change then, the next daily will be blocked for that component though (and only for that component) until your change reaches upstream. So please, be a good citizen and avoid more churn in proposing your change back to the upstream repo (including changelog), pinging the ubuntu-unity team preferably.
I'm making a source change, should I provide anything in debian/changelog?
Not really, as mentioned earlier, if you link to a bug or mention in a commit message a bug number in your branch before proposing for review, this will be taken into account and debian/changelog will be populated automatically with your name as part of the next daily release. You can still provide it manually and the daily release will ensure there is no duplication if it was already mentionned.
If you provide it manually, just: dch and ensure you have UNRELEASED for an unreleased version to ubuntu (without direct upload). Again, as mentioned earlier, it doesn't matter what version you choose whether you're making upstream changes or not. The daily release bot will ensure the changelog version is correct.
NOTE: please note that adding an entry to the changelog (or simply modifying it) usually results in a new release being triggered during the daily release. So only modify the changelog when there is something useful to release.
I'm making a packaging change, should I provide anything in debian/changelog?
Even though normally it is advised to document all packaging changes in debian/changelog, in our case it's something that needs to be thought through twice. As mentioned in the previous question, every modification of debian/changelog might force a new release for the given package. Sometimes it might not make sense.
For instance, if you modify the Vcs-Bzr tag of debian/control - such a change for sure should not force a new release. But if we would mention it in the changelog explicitly, it would trigger a package release during the next daily release. So, in such case, do not provide any changelog entry for such change.
So, to summarize: in MOST cases you should not provide anything in the changelog. If you do, remember to do it only if you want it to trigger a new release.
ubuntu-unity team
Note that in all following commands, if -r <release> is not provided, "head" is assumed. Also, ensure you have your credentials working and be connected to the VPN (the QA team is responsible for providing those jenkins credentials).
Where is the jenkins start page?
Forcing a stack publication
After reviewing and ensuring that we can release a stack (see section about manual publication causes, like packaging changes to review or upstream stack failing/in manual mode). Then run:
$ cu2d-run -P --force <stack_name> -r <release>
example for indicators, head release:
$ cu2d-run -P --force indicators
Remember that the master "head" job is not rerun, so it will stay in its current state (unstable/yellow). The publish job should though goes from unstable/yellow to green if everything went well.
Rerun a full stack daily release, rebuilding everything
$ cu2d-run -R <stack_name> -r <release>
Rerun a partial stack daily release, rebuilding only some components
$ cu2d-run -R <stack_name> -r <release> <components>
this will keep the state and take into account (failure to build state for instance) and the binaries packages for the other components which were part of this daily release, but not rebuilt.
for instance, keeping dee and libunity, but rebuilding compiz and unity from the unity, head release stack: $ cu2d-run -R unity compiz unity
The integration tests will still take everything we have (so including dee and libunity) at the latest stack with the new trunk content for compiz and unity when we relaunched this command.
Rerun integration tests, but taking all ubuntu-unity ppa's content (like transition needing publication of the indicator and unity stacks)
$ cu2d-run -R <stack_name> -r <release> --check-with-whole-ppa
This command doesn't rebuild anything, just run the "check" step, but with the whole ppa content (basically doing a dist-upgrading instead of selecting only desired components from this stack). This is handy when for instance a transition involved the indicator and unity stack. So the indicator integration tests failed (we don't have the latest unity stack built yet). Unity built and tests pass. To be able to release the indicator stack as well as the unity stack, we need the indicator stack to publish, for that, we relaunch only the indicator tests, but with the whole ppa content, meaning last Unity.
In that case, the publish for the indicators will be manual (you will need to force the publication) and as well, you should ensure that you will publish the unity stack at the same time as well to have everything in coherence copied to the -proposed pocket. More information on the stack dependency [DailyRelease/StackDependencies|in this section].
I know that I want for one time skipping one arch where my package won't built for
If one arch is build-dep wait and we know that it won't get unblock for this daily, it's possible to skip that over for this run using:
$ cu2d-skip -r <release> stack project archs [archs]
project is the source package name.
archs are space separated mentionning every archs we wait the wait-for-ppa to skip. Remember this is a one time thing. For longer-term, the packaging needs to be fixed to tell on what arch it's building its binaries packages (a detection is done when initializing the watcher).
Adding/removing components to a stack
The stack files are living in the stack/ folder of lp:cupstream2distro-config. This yaml file structure should be straightforward. Note that the tuple component: branch_location is optional (it will be set to lp:component if not provided). So add/change what you need in those file.
We now need to redeploy the stacks that have been modified. Before you do that, you need to ping an archive admin to modify the server-side filtering as well (see the end of this question). It's not necessarily needed to be done before redeploying, but this might save some trouble. After a stack is redeployed, you cannot run the publish job before pinging the archive admin. If you do, the package will be rejected from the queue, as the filtering mechanism will not have the new component enabled.
Be aware that all running jobs are stopped for this stack.
$ cu2d-update-stack -U <path_to_stack_file>
This will reset/reconfigure as well all branches, add -S if you don't have access to them (but ensure someone will configure them still at least once)
Then, ask an archive admin to pull the modification on snakefruit for the second-safety check process.
The archive admin needs to, after checking that lp:cupstream2distro only adds component for filtering we want:
$ ssh snakefruit.canonical.com $ sudo -u ubuntu-archive -i $ cd cu2d/cupstream2distro-config/ $ bzr pull
The server side filtering will be refreshed then. You are now ready to re-run the stack and publish your new components normally.
Adding a whole new stack
- Add a new config file to cu2d-config
- Deploy the config file(s)
- Do a bzr pull on magners
- At this point, the head job will appear _under_ "all" in Jenkins, and will be run with the next cycle
- To finalize, contact jibel to have a view created on the front page like for other stacks
Different level of failures acceptance
We do accept some integration tests failing (no unit tests should fail though as ran as part of package building). The different levels of those triggers are defined in a file like daily-release/config/autopilot.rc. Those are different level of failures, regressions, skipped and removed tests per stack. The real file depends on stackname and are found in ~jenkins/cu2d/<stack_name>.autopilotrc as described in the -check template.
Monitoring upstream uploads and merges
Remember to regularly look at the -changes mailing list to pick if a manual upload has been done and port the changes back (if not proposed by the ubuntu developer making the upload) to the upstream branch. The component which had a manual upload is ignored for daily release until this backport is done, meaning that no new commits will be published until then (you can see the prepare job for that component will turn unstable).
Also, ensure as you are watching all upstream merges to follow our acceptance criterias that the "latestsnapshot" branches generated automatically by the daily release process has been merged successfully by the upstream merger.
Boostrapping a new component for daily release
A lot of information is available on this wiki page.
General infos
How do we populate the changelog
I'm sure you want the world to know what great modifications you have introduced. You will get this praise automatically, using the commit message you set on the mainline (either automatically merged or by a manual merge to trunk) attributed to you. Note that we expurge some of the "Fixes" and "Approved by" messages that were eventually automatically generated as well as reformatting the commit to just be a one liner cut every 80 characters. If a branch merged to mainline had more than one contributor, each ones will get the praise (and blame ;)) in the changelog.
If you have a bug linking to this change, we are collecting it as well. This happens if you link bugs to a merge proposal before it's approved (you link a branch to the bug report in launchpad), or use bzr commit --fixes lp:XXXX so that automatically links it for you when proposing the merge for reviewing, or put in a commit message something like this fixes bug #….
Note that if you have directly edited debian/changelog in your merge proposal, this commit message will get ignored to avoid duplication (we consider you set all relevant infos there).
Also, if you are making a trivial change and don't want your typo fix to be listed, you can set "#nochangelog" into your commit message while merging to trunk and it will get ignored.
Versionning scheme
Head branches (trunks)
We needed to come with a sane versionning schema. The current one is: # based on current upstream version, like 6.5 # appending the current series version we target, betwen +<version>. like "+13.10." # adding the current date in yyyymmdd format So we end up with, for instance: 6.5+13.10.20130815. Then, we add -0ubuntu1 as the packaging is separated in the diff.gz by using split mode.
If we need to rerun the same day a release for the same component, as we detect that a version was already released in Ubuntu or eventually in the ppa, this will become: 6.5+13.10.2013085.1, and then 6.5+13.10.2013085.2… I think you got it
We can use this general pattern: <upstream_version>+<series_version>.<yyyymmdd(.minor)>-0ubuntu1 for the package. The next goal is to have upstream_version as small (one, two digits?) as possible.
Why using the +<series_version>, we already have the date?
This is when we start diverging trunk and a maintenance branch.
It is needed because we are going to release both to a maintenance branch and the new ubuntu release version, potentially even the same day. Without that, if upstream doesn't bump any upstream version, it means that 7.0.2013.05.02-0ubuntu1 can have a different content in the maintenance branch than in the new development version, while having exactly the same changelog version.
So, the maintenance branch version will be for instance 7.0+13.04.2013.05.02-0ubuntu1 and trunk will deliver 7.0+13.10.2013.05.02-0ubuntu1 to the development release (which will always have a higher version).
modification for feature branch
A feature branch will daily release in a separate ppa, and in a separate branch. We need to tweak the version (as in the previous section) to avoid that 7.0+13.10.20130502-0ubuntu1 in the distro and 7.0+13.10.20130502-0ubuntu1 in the ppa reference different content (and potentially, people dist-upgrading will have a mix of distro and feature ppa content).
To avoid that to happen, we are append the "destination ppa" (nothing for distro) to the version. So if we release in unity-team/next ppa, the version will be: 7.0+13.10.20130502unity.team.next-0ubuntu1