[gentoo-portage-dev] Re: [PATCH v4] Add repoman check to warn if src_prepare/src_configure are used in EAPI 0/1 and if pkg_pretend is used in EAPI < 4. Fixes bug 379491.

[Duncan]

Chris Reffett posted on Wed, 15 Jan 2014 16:35:48 -0500 as excerpted:

[snip the actual patch... and that's all the content there was]

TL;DR summary: please include commit descriptions and append one-line vN 
changelogs as the vN increases.

I'm not sure whether there's an accepted practice for portage or not, but 
on the various upstream mailing lists (mostly btrfs, AFAIK using the 
general lkml/kernel policy) I follow, accepted practice is to:

1) Always include a commit description.

2) For [PATCH vN] commits/posts, append to that description a short 
(generally but not always one-line) version changelog:

[Original commit description, generally unchanged unless a vN 
significantly changed something at the comment level.]

v2: Xxxx pointed out that I missed ...
v3: Oops, v2 was incomplete, ignore it
v4: Sebastian suggested I use eap_has_function instead of hardcoding EAPI

This makes is *FAR* easier for people to track a patch as it evolves, 
particularly if they've investigated an earlier version and now only care 
about what has changed since then, or if (like me) they don't really 
code, but are still interested in following the patch as it evolves, 
particularly if they've applied and are testing it!

Yes, people can go back and find the other version and do a diff, but the 
vN oneline changelog format is /so/ much easier, and people can still do 
a diff if they're actually interested once they read the one-line. =:^)

-- 
Duncan - List replies preferred.   No HTML msgs.
"Every nonfree program has a lord, a master --
and if you use the program, he is your master."  Richard Stallman