Summary

As presented in the Kubuntu/Specs/LucidPackaging, it is necessary and asked of the Kubuntu developers to keep the amount of patches as low as possible and ensure the highest possible quality of those that are necessary. This specification is targeting to formalize the rules regarding patching in order to archive aforementioned objectives.

Rationale

Over time more and more patches get added to packages, be it to fix bugs introduced by upstream, or to make the software fit better into the Kubuntu system. Each patch however requires a certain amount of maintenance, so it is desired to keep the amount of patches as low as possible, in order to keep developer resources free for more important things than maintaining patches. Additionally each patch comes with the risk of introducing an issue that would not have appeared with the canonical upstream source, once again increasing the maintenance efforts of such a patch.

It became apparent that patches expose the following issues:

This policy is expected to reduce the application of patches in Kubuntu, to reduce the exposure to above listed issues.

Developer stories

Assumptions

TODO?

Implementation

Rule Set

Before creating a patch it needs to be evaluated if another approach might not be better suited. For example most default changes in KDE can be carried out via kubuntu-default-settings. Please also note that additions to kubuntu-default-settings should generally be considered patches too, and discussed with upstream whether it is not appropriate to also apply the change in the upstream source code.

Should it indeed be necessary to carry out a code change it is important that some basic rules need to be kept in mind.

In general it should be tried to implement solutions that qualify for upstream inclusion, so that ultimately no patch is necessary at all, or only for the short amount of time between a Kubuntu release and a new upstream release.

Should it not be possible to do that either, then the following rules apply.

Patches adding more than 25 source lines of code, or more than 2 functions, or changing the interface of a function, must be reviewed and approved by upstream before inclusion into Kubuntu. This is because the large a patch is, the large is the risk of regression compared to upstream. Patches adding less than 25 source lines of code, are also preferred to be reviewed by upstream. Patches must not be taken from any bug tracker, without being reviewed by upstream or someone who is familiar with the source base.

Patches adding more than 200 source lines of code, or more than 4 functions, or requiring public API changes must be done upstream, unless they are 100% necessary for Kubuntu, and would cause malfunction or bugs if not applied (language-pack integration would be such a case). Even then upstream needs to be made aware and at least approve the patch's existence.

Merging

In course of merging our packages with Debian's at the beginning of each cycle, also each patch should be reviewed towards upstreamability to KDE or Debian. Should a patch qualify, it should be proposed to the appropriate person(s) so that it can be applied upstream.

Naming

In order to make it more apparent where a patch comes from the following naming scheme should be applied for all Kubuntu patches (please note that patches imported from Debian will always be considered as such, despite any source Debian might have it from).

The general naming scheme is: <creator>_<counter>_<description>.patch

For example, the second patch imported from Amarok's git branch might look like this: amarok_02_fix_playlist_model.patch

Creator is always the party who created the patch, if we imported a patch from mandriva, the first creator part would be "mandriva" and so on. The counter is a progressing counter of patches, while merging a package from Debian the counters should be compressed, otherwise new patches should always be stacked upon the latest one from the creator, even if there are open numbers in the lower range. This is very nice to have since it gives a bit of an idea of how many patches we added over a cycle and how many of those we were able to get rid of again.

KDE SVN

For patches from KDE's SVN for the KDE SC (i.e. not extragear, or playground or anything else) a special rule applies to the counter. If the patch was imported from the SVN branch that is supposed to be released as $CURRENTVERSION.1, then the counter starts at 100, for .2 the counter starts at 200... Patches imported from trunk start counting at 900.

A possible patch set looks like this:

Obviously something is wrong in this example, since we have both a patch that should be in .1 and one that should be in .2, so say we are at 4.4.1, something went wrong and kde_100_barfoo.patch was not applied upstream, so a developer should go look what happened to the change. This is mostly the rationale of this additional versioning scheme.

KDE Bug Tracker

Patches originating from bugs.kde.org, approved by upstream, but not yet applied anywhere in SVN ought to use "bko" as creator and use the bug number as counter.

bko_666666_fix_crash.patch

Example

BoF agenda and discussion


CategorySpec

Kubuntu/Specs/MaverickPatchPolicy (last edited 2010-05-08 09:21:10 by apachelogger)