1 |
Chris Reffett posted on Wed, 15 Jan 2014 16:35:48 -0500 as excerpted: |
2 |
|
3 |
[snip the actual patch... and that's all the content there was] |
4 |
|
5 |
TL;DR summary: please include commit descriptions and append one-line vN |
6 |
changelogs as the vN increases. |
7 |
|
8 |
I'm not sure whether there's an accepted practice for portage or not, but |
9 |
on the various upstream mailing lists (mostly btrfs, AFAIK using the |
10 |
general lkml/kernel policy) I follow, accepted practice is to: |
11 |
|
12 |
1) Always include a commit description. |
13 |
|
14 |
2) For [PATCH vN] commits/posts, append to that description a short |
15 |
(generally but not always one-line) version changelog: |
16 |
|
17 |
[Original commit description, generally unchanged unless a vN |
18 |
significantly changed something at the comment level.] |
19 |
|
20 |
v2: Xxxx pointed out that I missed ... |
21 |
v3: Oops, v2 was incomplete, ignore it |
22 |
v4: Sebastian suggested I use eap_has_function instead of hardcoding EAPI |
23 |
|
24 |
This makes is *FAR* easier for people to track a patch as it evolves, |
25 |
particularly if they've investigated an earlier version and now only care |
26 |
about what has changed since then, or if (like me) they don't really |
27 |
code, but are still interested in following the patch as it evolves, |
28 |
particularly if they've applied and are testing it! |
29 |
|
30 |
Yes, people can go back and find the other version and do a diff, but the |
31 |
vN oneline changelog format is /so/ much easier, and people can still do |
32 |
a diff if they're actually interested once they read the one-line. =:^) |
33 |
|
34 |
-- |
35 |
Duncan - List replies preferred. No HTML msgs. |
36 |
"Every nonfree program has a lord, a master -- |
37 |
and if you use the program, he is your master." Richard Stallman |