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
signature.asc
Description: PGP signature
