docs/transitions.txt

   1 Contents:
   2
   3 1. Little "Howto Use it"
   4 2. Explanation of how it works
   5
   6
   7 1. Little "Howto Use it"
   8 ------------------------
   9
  10 The input file is in YAML format. Do not bother with comments, they
  11 will be removed.
  12
  13 The format: Don't use tabs for indentation, use spaces.
  14
  15 Strings should be within "", but normally work without.
  16 Exception: Version-numbers with an epoch really do want to be in
  17 "". YES, THEY WANT TO (or they get interpreted in a way you don't expect
  18 it).
  19
  20 Keys (The order of them does not matter, only the indentation):
  21
  22 short_tag:    A short tag for the transition, like apt_update
  23   reason:     One-line reason what is intended with it
  24   source:     Source package that needs to transition
  25   new:        New version of the target package
  26   rm:         Name of the Release Team member responsible for this transition
  27   packages:   Array of package names that are affected by this transition
  28
  29
  30 The following example wants to
  31 a.) update apt to version 0.7.12, the responsible Release Team member
  32 is Andreas Barth, and it affects some apt related packages and
  33 b.) wants to do something similar for lintian.
  34
  35 apt_update:
  36   packages:
  37     - apt
  38     - synaptic
  39     - cron-apt
  40     - debtags
  41     - feta
  42     - apticron
  43     - aptitude
  44   reason: "Apt needs to transition to testing to get foo and bar done"
  45   source: apt
  46   new: 0.7.12
  47   rm: Andreas Barth
  48 lintian_breakage:
  49   reason: "Testing a new feature"
  50   source: lintian
  51   new: 1.23.45~bpo40+1
  52   rm: Ganneff
  53   packages:
  54     - lintian
  55     - python-syck
  56
  57
  58 ########################################################################
  59 ########################################################################
  60
  61
  62 2. Explanation of how it works
  63 ------------------------------
  64
  65 Assume the following transition is defined:
  66
  67 lintian_funtest:
  68   reason: "Testing a new feature"
  69   source: lintian
  70   new: 1.23.45~bpo40+1
  71   rm: Ganneff
  72   packages:
  73     - lintian
  74     - python-syck
  75
  76 Also assume the lintian situation on this archive looks like this:
  77    lintian | 1.23.28~bpo.1 | sarge-backports | source, all
  78    lintian | 1.23.45~bpo40+1 | etch-backports | source, all
  79
  80 ------------------------------------------------------------------------
  81
  82 Now, I try to upload a (NEW, but that makes no difference) version of
  83 python-syck:
  84
  85 $ dak process-unchecked -n python-syck_0.61.2-1~bpo40+1_i386.changes
  86
  87 python-syck_0.61.2-1~bpo40+1_i386.changes
  88 REJECT
  89 Rejected: python-syck: part of the lintian_funtest transition.
  90
  91 Your package is part of a testing transition designed to get lintian migrated
  92 (it currently is at version 1.23.28~bpo.1, we need version 1.23.45~bpo40+1)
  93
  94 Transition description: Testing a new feature
  95
  96 This transition is managed by the Release Team, and Ganneff
  97 is the Release-Team member responsible for it.
  98 Please contact Ganneff or debian-release@lists.debian.org if you
  99 need further assistance.
 100
 101 ------------------------------------------------------------------------
 102
 103 Lets change the definition of the transition, assume it is now:
 104
 105 lintian_funtest:
 106   reason: "Testing a new feature"
 107   source: lintian
 108   new: 1.22.28~bpo.1
 109   rm: Ganneff
 110   packages:
 111     - lintian
 112     - python-syck
 113
 114 Which checks for a version older than the version actually available. Result:
 115
 116 dak process-unchecked -n python-syck_0.61.2-1~bpo40+1_i386.changes
 117
 118 python-syck_0.61.2-1~bpo40+1_i386.changes
 119 NEW for etch-backports
 120 (new) python-syck_0.61.2-1~bpo40+1.diff.gz extra python
 121 (new) python-syck_0.61.2-1~bpo40+1.dsc extra python
 122 (new) python-syck_0.61.2-1~bpo40+1_i386.deb extra python
 123 PySyck python bindings to the Syck YAML parser kit
 124  Syck is a simple YAML parser kit.
 125  .
 126 [...] the whole stuff about a new package.
 127
 128 ------------------------------------------------------------------------
 129
 130 For completeness, change the transition to (exact existing version):
 131 lintian_funtest:
 132   reason: "Testing a new feature"
 133   source: lintian
 134   new: 1.23.28~bpo.1
 135   rm: Ganneff
 136   packages:
 137     - lintian
 138
 139 and the result is:
 140
 141 dak process-unchecked -n python-syck_0.61.2-1~bpo40+1_i386.changes
 142
 143 python-syck_0.61.2-1~bpo40+1_i386.changes
 144 NEW for etch-backports
 145 [... we know this ...]
 146
 147 ------------------------------------------------------------------------
 148
 149 The second part is the check_transitions script.
 150 For that we take the following transitions as example:
 151
 152 apt_update:
 153   reason: "Apt needs to transition to testing to get foo and bar done"
 154   source: apt
 155   new: 0.2.12-1+b1.3
 156   rm: Andreas Barth
 157   packages:
 158     - apt
 159     - synaptic
 160     - cron-apt
 161     - debtags
 162     - feta
 163     - apticron
 164     - aptitude
 165 lintian_funtest:
 166   reason: "Testing a new feature"
 167   source: lintian
 168   new: 1.23.45~bpo40+1
 169   rm: Ganneff
 170   packages:
 171     - lintian
 172     - python-syck
 173 bar_breaks_it:
 174   reason: We don't want bar to break it
 175   source: bar
 176   new: "9:99"
 177   rm: Ganneff
 178   packages:
 179     - kdelibs
 180     - qt4-x11
 181     - libqt-perl
 182
 183 Running check-transitions ends up with the following output:
 184
 185 Looking at transition: lintian_funtest
 186  Source:      lintian
 187  New Version: 1.23.45~bpo40+1
 188  Responsible: Ganneff
 189  Description: Testing a new feature
 190  Blocked Packages (total: 2): lintian, python-syck
 191
 192 Apt compare says: -2
 193 This transition is still ongoing, we currently have version 1.23.28~bpo.1
 194 -------------------------------------------------------------------------
 195
 196 Looking at transition: apt_update
 197  Source:      apt
 198  New Version: 0.2.12-1+b1.3
 199  Responsible: Andreas Barth
 200  Description: Apt needs to transition to testing to get foo and bar done
 201  Blocked Packages (total: 7): apt, synaptic, cron-apt, debtags, feta, apticron, aptitude
 202
 203 Apt compare says: 4
 204 This transition is over, the target package reached testing, removing
 205 apt wanted version: 0.2.12-1+b1.3, has 0.6.46.4-0.1~bpo.1
 206 -------------------------------------------------------------------------
 207
 208 Looking at transition: bar_breaks_it
 209  Source:      bar
 210  New Version: 9:99
 211  Responsible: Ganneff
 212  Description: We don't want bar to break it
 213  Blocked Packages (total: 3): kdelibs, qt4-x11, libqt-perl
 214
 215 Transition source bar not in testing, transition still ongoing.
 216 -------------------------------------------------------------------------
 217 I: I would remove the apt_update transition
 218
 219
 220 Changing our transition definitions for lintian (keeping the rest as
 221 above) to
 222
 223 lintian_funtest:
 224   reason: "Testing a new feature"
 225   source: lintian
 226   new: 1.22.28~bpo.1
 227   rm: Ganneff
 228   packages:
 229     - lintian
 230     - python-syck
 231
 232 now we get
 233
 234 Looking at transition: lintian_funtest
 235  Source:      lintian
 236  New Version: 1.22.28~bpo.1
 237  Responsible: Ganneff
 238  Description: Testing a new feature
 239  Blocked Packages (total: 2): lintian, python-syck
 240
 241 Apt compare says: 1
 242 This transition is over, the target package reached testing, removing
 243 lintian wanted version: 1.22.28~bpo.1, has 1.23.28~bpo.1
 244 -------------------------------------------------------------------------
 245
 246 Looking at transition: apt_update
 247  Source:      apt
 248  New Version: 0.2.12-1+b1.3
 249  Responsible: Andreas Barth
 250  Description: Apt needs to transition to testing to get foo and bar done
 251  Blocked Packages (total: 7): apt, synaptic, cron-apt, debtags, feta, apticron, aptitude
 252
 253 Apt compare says: 4
 254 This transition is over, the target package reached testing, removing
 255 apt wanted version: 0.2.12-1+b1.3, has 0.6.46.4-0.1~bpo.1
 256 -------------------------------------------------------------------------
 257
 258 Looking at transition: bar_breaks_it
 259  Source:      bar
 260  New Version: 9:99
 261  Responsible: Ganneff
 262  Description: We don't want bar to break it
 263  Blocked Packages (total: 3): kdelibs, qt4-x11, libqt-perl
 264
 265 Transition source bar not in testing, transition still ongoing.
 266 -------------------------------------------------------------------------
 267 I: I would remove the lintian_funtest transition
 268 I: I would remove the apt_update transition
 269
 270
 271 Not using the -n switch would turn the I: in actual removals :)
 272 The check-transition command is meant for the release team to always run
 273 it when they change a transition definition. It checks if the yaml is
 274 valid and can be loaded (but if not the archive simply does no reject)
 275 and also shows a nice overview.