MaverickPatchPolicy

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:

  • Deriving from canonical upstream source means that upstream can not give their best support, increasing the amount of support and bug tracking/management/fixing in Kubuntu.
  • Deriving from canonical upstream source bares a mostly great risk of introducing bugs, since the patch author will most likely not be an upstream author, hence might not fully be aware of their change's implications.
  • Deriving from canonical upstream source will make upstream grumpy with Kubuntu, since some users will always report issues to the upstream authors, even if they are not responsible, nor knew anything about the code causing the issues.
  • Deriving from canonical upstream source means that a delta gets added that needs to be maintained by the Kubuntu developers.
  • Introducing a delta to the upstream source base almost certainly inflicts that someone who did not create the patch, nor knows nothing about the upstream source, will have to struggle with updating the delta in case upstream changed the affected source portions around.

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

Developer stories

  • Kevin is a KDE developer and bug triager. Every once in a while, Thomas strives through the KDE bug tracking system, triaging bugs. He is very happy that, unlike other distributions, Kubuntu does not seem to apply large amounts of buggy patches, and he does never hit a bug that was caused by Kubuntu.
  • Fathi is a Debian developer and very happy that every once in a while he gets told about the latest and greatest Kubuntu patches, that might be interesting for Debian, so he can incorporate them in Debian and make Debian a better product.
  • Scott is a Kubuntu developer and glad that he does not have to update 30 patches for each new KDE release.
  • Jonathan is also a Kubuntu developer and likes that he can spend most of his time developing new cool stuff in stead of digging through endless amounts of bug reports that were caused by a patch some unknown developer wrote 5 years ago.

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:

  • kubuntu_01_foo.patch - Kubuntu specific
  • kde_01_bar.patch - Unknown origin within KDE
  • kde_100_barfoo.patch - Coming from stable branch
  • kde_200_foobar.patch - Coming from stable branch
  • kde_900_pony.patch - Coming from trunk

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

  • kubuntu_01_change_menu_install_path.patch - Kubuntu specific, not upstreamable
  • kubuntu_03_change_icon_install_path.patch - Kubuntu specific, not upstreamable, apparently kubuntu_02 was removed at some point in this cycle
  • kde_01_fix_crash_at_init.patch - Unknown origin within KDE
  • kde_300_fix_icon_loading.patch - Coming from stable branch, should be droppable in the .3 release
  • kde_900_buttons_on_the_left.patch - Coming from trunk, should be droppable in some release of the next major version
  • bko_999999_stop_whining.patch - Coming from bugs.kde.org bug #999999
  • fedora_01_break_something.patch - Coming from fedora

BoF agenda and discussion

CategorySpec

Kubuntu/Specs/MaverickPatchPolicy (last edited 2010-05-08 09:21:10 by 84-119-17-48)