patch naming policy

Horms horms at
Wed Apr 6 03:31:02 UTC 2005

On Tue, Apr 05, 2005 at 07:29:09PM -0400, Andres Salomon wrote:
> On Tue, 05 Apr 2005 18:13:43 +0200, Fabio Massimo Di Nitto wrote:
> [...]
> > 
> > I have rarely seen patches that were touching more than one kernel TOPDIR at the same time
> > (exception for include/) so i would say that the dirs in TOPDIR could easily define
> > the first set of delimiters..
> > 
> For debian, we tend to have patches based on the actual path to the files
> that are being touched; that works well.  So, for drivers,
> drivers-net-tg3-frobnicate.patch; for arch-specific stuff,
> arch-i386-corrupt_memory.patch.  Of course, it's a judgement call when a
> patch touches things in multiple top level directories, but it's usually
> fairly easy to determine what it should be (ie, the asfs patch adds stuff
> to Documentation, but it's clearly not a documentation-specific patch;
> it's a filesystem patch, so fs-asfs.patch is what we call it).  If it's a
> patch that touches a lot of directories, I'll use top-most common
> directory (ie, drivers-pci_update_something.patch, that updates something
> pci related on a number of net, char, and ide drivers).

In the 2.4 debian tree patches are also incremented with a monotonically
increasing serial number. Its a bit ad-hoc but generally the first
patch is 001-blah, then 002-blah. If patches come toghether they
can be grouped under the same serial number to make it slightly
more obvous they came together. e.g. 123-fs-isofs-leak-1, 
123-fs-isofs-leak-2, 123-fs-isofs-leak-3. I find this very useful
for quickly deterimining the relative age of patches in the tree,
though I am not religious about it.

> > the second part should usually be a very short explanation of what the
> > patch does. Reserve all the comments for a detailed changelog entry.
> > 
> The main problem we've found w/ this has been related to patches that do
> the same thing.  For example, the various mm/ and fs/ files for elf and
> mmap related security things end up looking like
> 'fs-fix-int-overflow.patch'.  Then, another integer overflow is found, and
> you end up w/ 'fs-fix-int-overflow-2.patch'.  So, what I'll tend to do is,
> if it's a widespread change across multiple functions or files, I'll
> simply describe it ('drivers-dont-unregister-netdev-before-alloc.patch'). 
> If it's local to a function, I'll include the function name
> ('mm-do_mmap_pgoff-race-fix').  This helps a lot when multiple related
> fixes are made to the same file, but all w/ the same goal, and across
> different bk changesets.

I think the imporatnt thing here is to include a comment in the
patch that describes where it came from, what can it fixes, etc.
If the patch comes from bitkeeper this is pretty easy to do, 
as they are usually commented (sans can number). Otherewise
its not to hard to write something like.

Fix for missing clock chips to allow blade servers to be detected
Source: Dave Miller
Upstream Status: Present
Date: 25th March 2005

At the very least this can be used to correlate it against changes
that turn up in other trees. Though more information would be better.

> Also, since stolen-from-head is so common, you might consider shortening
> it to SFH or something, and having it be put at the end of the
> description.  So, drivers-media-video-saa7134-update-SFH.patch, or
> something like that; a quick 'ls *SFH.patch' allows you to see which
> patches are backports (same as you get now w/ the leading
> stolen-from-head*, but w/out making obscenely long filenames).



More information about the kernel-team mailing list