Klaus Heinz wrote:
> 
> For all commits we need descriptions what the changes are supposed to do.
> The descriptions can be contained in the commit message for _all_ files
> (see example below) or take the form of pkgsrc-specific comments either at
> the start of the patch describing all the patch hunks or the hunks need
> to include the comments so they are visible in the patched source files.

I favor including comments in-line with the code in the patches.  This 
makes it more likely for the patches to be taken upstream because the 
code diff contains comments that the upstream authors can easily 
associate with the code that they didn't write themselves, and those 
same comments also often become part of the main code repository.

> Patch files should refer to a single source file name during the entire
> life of a package. If the file does not need to be patched anymore, the
> name of the patch file must not be reused for different source files.
> 
> I think the latter rule would be much easier to follow if we adopted the
> FreeBSD practice of naming patch files after the source files they are
> changing.

For the packages that I maintain, I painstakingly try to ensure that 
each patch only affects the same file for the lifetime of the package. 
When a new file in a newer version of the package needs to be patches, I 
pick a new patch-[a-z][a-z] name rather than re-use any patch names that 
existed before.  When a file was patched in an older version of the 
package and needs to be patched in a newer version, I check the CVS 
Attic for the name of the corresponding patch.

Of course, this is all just a lot of busywork -- if we had a simple, 
consistent way to canonicalize filename to patch name, e.g. FreeBSD 
Ports / -> :: method, then all this extra work would be unnecessary.  I 
can't imagine anyone really thinks names like "patch-ak" are useful in 
any meaningful sense of the word.  FWIW, I use the FreeBSD Ports 
patch-naming scheme in the package system I wrote for work.

	Cheers,

	-- Johnny C. Lam