[gentoo-dev] [RFC] Establishing Gentoo patch policy to keep our patches consistent and clean

[Michał Górny]

Hello,

As far as I'm aware, we don't really have much of a patch maintenance
policy in Gentoo. There a few loose rules like «don't put awfully big
files into FILESDIR» or the common sense «use unified diff», but no
complete and clear policy.

Especially considering the late discussion related to the needless
and semi-broken functionality in epatch, I'd like to propose
setting the following rules for patches in tree and in Gentoo-sourced
patchsets:

1. Patches have to be either in unified or context diff format. Unified
diff is preferred.

2. Patches have to apply to the top directory of the source tree with
'patch -p1'. If patches are applied to sub-directories, necessary '-p'
argument shall be passed to 'epatch' explicitly. Developers are
encouraged to create patches which are compatible with 'git am'.

3. Patches have to end with either '.patch' or '.diff' suffix.

4. If possible, patches shall be named in a way allowing them to be
applied in lexical order. However, this one isn't necessary if patches
from an older ebuild are applied to a newer one.

5. The patch name shall shortly summarize the changes done by it.

6. Patch files shall start with a brief description of what the patch
does. Developers are encouraged to use git-style tags like 'Fixes:' to
point to the relevant bug URIs.

7. Patch combining is discouraged. Developers shall prefer multiple
patches following either the upstream commits or a logical commit
sequence (if changes are not committed upstream).

The above-listed policy will apply to the patches kept in the gx86 tree
(in FILESDIRs) and patch archives created by Gentoo developers. They
will not apply to the patch archives created upstream.


RATIONALE
---------

The main reason for the whole policy is to let Gentoo supply users with
consistent and friendly patches. That is, patches which can be used
directly on a source tree or submitted upstream without any additional
actions from user.

(1) lists the most common patch formats. The formats shall be generally
both readable and reusable whenever possible. I wanted just 'unified
diff' but ulm suggested that we should also support those upstreams who
use 'context diffs'.


(2) is likely to be a bikeshed point here. Long story short, epatch has
this fragile patchlevel guessing, users don't have it. If we keep our
patches consistent to a single patchlevel, we gain:

* ability for users to apply the patches without having them try all
  patchlevels by hand.

* clean error output if patch stops to apply for some reason.

* no risk that patch will get applied to the wrong file if patch stops
  to apply at expected patchlevel and starts to apply on another.

Also, by creating git-format patches, we gain the ability of rebasing
and updating the patches easily. Even with non-git upstreams, we can
do:

  git init; git add -A; git commit -m 1; git am ...


(3) should be mostly obvious. The main idea is that if we apply a whole
patchdir, we should be able to easily tell between patches
and auxiliary files like 'README' or Debian's 'series'.

I have never seen a patch file named other than '*.patch' or '*.diff'.
Therefore, I think that it's better to just require those rather than
trying to provide a sane list of excludes.


(4) is mostly about friendliness (again). Since shell does filename
expansion in lexical order, it's just great for user to be able apply
patches like:

  git am /usr/portage/foo/bar/files/198-*.patch

The other sentence is not to enforce this rule e.g. when the same patch
is applied to different versions of the same package. Although with
a fair of trickery that could be gotten working, I don't think it will
be user-friendly anymore :).


(5) makes finding a particular patch of interest easier, while (6)
makes sure that the purpose of the patch can be read from patch alone.
In both cases, having described patches is much better than having to
look into ebuilds for explanations.


(7) is because merged patches are usually hard to read and completely
not suitable for submitting anywhere.


What are your thoughts?

-- 
Best regards,
Michał Górny