Gentoo Archives: gentoo-dev

From: "Michał Górny" <mgorny@g.o>
To: Gentoo Developer Mailing List <gentoo-dev@l.g.o>
Subject: [gentoo-dev] [RFC] Establishing Gentoo patch policy to keep our patches consistent and clean
Date: Sat, 06 Apr 2013 18:08:57
Message-Id: 20130406200843.6831c4fe@pomiocik.lan
1 Hello,
3 As far as I'm aware, we don't really have much of a patch maintenance
4 policy in Gentoo. There a few loose rules like «don't put awfully big
5 files into FILESDIR» or the common sense «use unified diff», but no
6 complete and clear policy.
8 Especially considering the late discussion related to the needless
9 and semi-broken functionality in epatch, I'd like to propose
10 setting the following rules for patches in tree and in Gentoo-sourced
11 patchsets:
13 1. Patches have to be either in unified or context diff format. Unified
14 diff is preferred.
16 2. Patches have to apply to the top directory of the source tree with
17 'patch -p1'. If patches are applied to sub-directories, necessary '-p'
18 argument shall be passed to 'epatch' explicitly. Developers are
19 encouraged to create patches which are compatible with 'git am'.
21 3. Patches have to end with either '.patch' or '.diff' suffix.
23 4. If possible, patches shall be named in a way allowing them to be
24 applied in lexical order. However, this one isn't necessary if patches
25 from an older ebuild are applied to a newer one.
27 5. The patch name shall shortly summarize the changes done by it.
29 6. Patch files shall start with a brief description of what the patch
30 does. Developers are encouraged to use git-style tags like 'Fixes:' to
31 point to the relevant bug URIs.
33 7. Patch combining is discouraged. Developers shall prefer multiple
34 patches following either the upstream commits or a logical commit
35 sequence (if changes are not committed upstream).
37 The above-listed policy will apply to the patches kept in the gx86 tree
38 (in FILESDIRs) and patch archives created by Gentoo developers. They
39 will not apply to the patch archives created upstream.
43 ---------
45 The main reason for the whole policy is to let Gentoo supply users with
46 consistent and friendly patches. That is, patches which can be used
47 directly on a source tree or submitted upstream without any additional
48 actions from user.
50 (1) lists the most common patch formats. The formats shall be generally
51 both readable and reusable whenever possible. I wanted just 'unified
52 diff' but ulm suggested that we should also support those upstreams who
53 use 'context diffs'.
56 (2) is likely to be a bikeshed point here. Long story short, epatch has
57 this fragile patchlevel guessing, users don't have it. If we keep our
58 patches consistent to a single patchlevel, we gain:
60 * ability for users to apply the patches without having them try all
61 patchlevels by hand.
63 * clean error output if patch stops to apply for some reason.
65 * no risk that patch will get applied to the wrong file if patch stops
66 to apply at expected patchlevel and starts to apply on another.
68 Also, by creating git-format patches, we gain the ability of rebasing
69 and updating the patches easily. Even with non-git upstreams, we can
70 do:
72 git init; git add -A; git commit -m 1; git am ...
75 (3) should be mostly obvious. The main idea is that if we apply a whole
76 patchdir, we should be able to easily tell between patches
77 and auxiliary files like 'README' or Debian's 'series'.
79 I have never seen a patch file named other than '*.patch' or '*.diff'.
80 Therefore, I think that it's better to just require those rather than
81 trying to provide a sane list of excludes.
84 (4) is mostly about friendliness (again). Since shell does filename
85 expansion in lexical order, it's just great for user to be able apply
86 patches like:
88 git am /usr/portage/foo/bar/files/198-*.patch
90 The other sentence is not to enforce this rule e.g. when the same patch
91 is applied to different versions of the same package. Although with
92 a fair of trickery that could be gotten working, I don't think it will
93 be user-friendly anymore :).
96 (5) makes finding a particular patch of interest easier, while (6)
97 makes sure that the purpose of the patch can be read from patch alone.
98 In both cases, having described patches is much better than having to
99 look into ebuilds for explanations.
102 (7) is because merged patches are usually hard to read and completely
103 not suitable for submitting anywhere.
106 What are your thoughts?
108 --
109 Best regards,
110 Michał Górny


File name MIME type
signature.asc application/pgp-signature