Gentoo Archives: gentoo-dev

From: Ryan Hill <dirtyepic@g.o>
To: gentoo-dev@l.g.o
Subject: [gentoo-dev] Re: [RFC] Establishing Gentoo patch policy to keep our patches consistent and clean
Date: Tue, 30 Apr 2013 04:34:21
Message-Id: 20130429224414.6b5e94a8@caribou.gateway.2wire.net
In Reply to: [gentoo-dev] [RFC] Establishing Gentoo patch policy to keep our patches consistent and clean by "Michał Górny"
1 On Sat, 6 Apr 2013 20:08:43 +0200
2 Michał Górny <mgorny@g.o> wrote:
3
4 > Hello,
5 >
6 > As far as I'm aware, we don't really have much of a patch maintenance
7 > policy in Gentoo. There a few loose rules like «don't put awfully big
8 > files into FILESDIR» or the common sense «use unified diff», but no
9 > complete and clear policy.
10 >
11 > Especially considering the late discussion related to the needless
12 > and semi-broken functionality in epatch, I'd like to propose
13 > setting the following rules for patches in tree and in Gentoo-sourced
14 > patchsets:
15 >
16 > 1. Patches have to be either in unified or context diff format. Unified
17 > diff is preferred.
18
19 Yes.
20
21 > 2. Patches have to apply to the top directory of the source tree with
22 > 'patch -p1'. If patches are applied to sub-directories, necessary '-p'
23 > argument shall be passed to 'epatch' explicitly. Developers are
24 > encouraged to create patches which are compatible with 'git am'.
25
26 Bikeshedding below.
27
28 > 3. Patches have to end with either '.patch' or '.diff' suffix.
29
30 Yes.
31
32 > 4. If possible, patches shall be named in a way allowing them to be
33 > applied in lexical order. However, this one isn't necessary if patches
34 > from an older ebuild are applied to a newer one.
35
36 Even more below.
37
38 > 5. The patch name shall shortly summarize the changes done by it.
39
40 Yes.
41
42 > 6. Patch files shall start with a brief description of what the patch
43 > does. Developers are encouraged to use git-style tags like 'Fixes:' to
44 > point to the relevant bug URIs.
45
46 Yes.
47
48 > 7. Patch combining is discouraged. Developers shall prefer multiple
49 > patches following either the upstream commits or a logical commit
50 > sequence (if changes are not committed upstream).
51
52 Kinda.
53
54 >
55 > The above-listed policy will apply to the patches kept in the gx86 tree
56 > (in FILESDIRs) and patch archives created by Gentoo developers. They
57 > will not apply to the patch archives created upstream.
58 >
59 >
60 > RATIONALE
61 > ---------
62 >
63 > The main reason for the whole policy is to let Gentoo supply users with
64 > consistent and friendly patches. That is, patches which can be used
65 > directly on a source tree or submitted upstream without any additional
66 > actions from user.
67 >
68 > (1) lists the most common patch formats. The formats shall be generally
69 > both readable and reusable whenever possible. I wanted just 'unified
70 > diff' but ulm suggested that we should also support those upstreams who
71 > use 'context diffs'.
72 >
73 >
74 > (2) is likely to be a bikeshed point here. Long story short, epatch has
75 > this fragile patchlevel guessing, users don't have it. If we keep our
76 > patches consistent to a single patchlevel, we gain:
77 >
78 > * ability for users to apply the patches without having them try all
79 > patchlevels by hand.
80 >
81 > * clean error output if patch stops to apply for some reason.
82 >
83 > * no risk that patch will get applied to the wrong file if patch stops
84 > to apply at expected patchlevel and starts to apply on another.
85
86 If I can't drop patches from an upstream mailing list with a different repo
87 structure than source, or just a random user who doesn't know better, into my
88 patchdir I'm going to be very grumpy.
89
90 Our patches should be -p1, I agree. I respin any patches I find that aren't.
91
92 The first two points are nice, but not worth it to me in particular. The third
93 I don't see the risk. What are the chances of that patch actually applying
94 successfully? It'll fail, and you root it out. And since all our own patches
95 will be -p1 this becomes a tiny corner case.
96
97
98 > Also, by creating git-format patches, we gain the ability of rebasing
99 > and updating the patches easily. Even with non-git upstreams, we can
100 > do:
101 >
102 > git init; git add -A; git commit -m 1; git am ...
103 >
104 > (3) should be mostly obvious. The main idea is that if we apply a whole
105 > patchdir, we should be able to easily tell between patches
106 > and auxiliary files like 'README' or Debian's 'series'.
107 >
108 > I have never seen a patch file named other than '*.patch' or '*.diff'.
109 > Therefore, I think that it's better to just require those rather than
110 > trying to provide a sane list of excludes.
111 >
112 >
113 > (4) is mostly about friendliness (again). Since shell does filename
114 > expansion in lexical order, it's just great for user to be able apply
115 > patches like:
116 >
117 > git am /usr/portage/foo/bar/files/198-*.patch
118 >
119 > The other sentence is not to enforce this rule e.g. when the same patch
120 > is applied to different versions of the same package. Although with
121 > a fair of trickery that could be gotten working, I don't think it will
122 > be user-friendly anymore :).
123
124 That's useful but ${PN}-${PV}-desc.patch is the currently accepted convention.
125 What you're suggesting here is a suggested workflow. I don't think it belongs
126 in a policy doc, at least as it's own section, or at least until it becomes
127 more commonplace.
128
129 > (5) makes finding a particular patch of interest easier, while (6)
130 > makes sure that the purpose of the patch can be read from patch alone.
131 > In both cases, having described patches is much better than having to
132 > look into ebuilds for explanations.
133 >
134 >
135 > (7) is because merged patches are usually hard to read and completely
136 > not suitable for submitting anywhere.
137
138 Well, patches should do one thing, agreed. But I'm not adding 4 patches to
139 respect LDFLAGS, use CFLAGS while linking, install into /usr, and fix the
140 version number in a 30 line Makefile. I'm adding foo-0.01-makefile.patch which
141 does one thing (fixes crappy-ass Makefile). I can live with "discouraged" though.
142
143
144 --
145 gcc-porting
146 toolchain, wxwidgets
147 @ gentoo.org

Attachments

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