1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
|
<?xml version="1.0"?>
<guide self="ebuild-writing/misc-files/changelog/">
<chapter>
<title>ChangeLog</title>
<body>
<p>
The <c>ChangeLog</c> must be updated with each commit. The
<uri link="::tools-reference/echangelog/">echangelog tool</uri> should be used to create <c>ChangeLog</c> entries;
the format of a <c>ChangeLog</c> is now defined as "whatever
<c>echangelog</c> creates".
</p>
<p>
You should include references to any relevant bugs. The standard
format for doing this is via the phrase <c>bug #20600</c> — this
format (with the hash sign included) is recognised via
<uri link="http://packages.gentoo.org">packages.gentoo.org</uri> and
similar tools. When including user-submitted ebuilds or patches, you
should credit the user with their full name and email address (or
whatever they use to identify themselves on bugzilla <d/> some users
prefer to be known only by a nickname).
</p>
<p>
If you are changing keywords, make sure you clearly state what
keywords you add or remove. "Marked stable" is a nuisance for
architecture teams, even if there was only one keyword in the ebuild
at the time. "Stable on all archs" isn't generally any better (and
should you really be stabling on all archs?) — do you mean "all", or
"all the ones that are currently keyworded"? A list like "x86 sparc
mips" is much more useful.
</p>
<p>
A typical <c>ChangeLog</c> snippet might look like the following:
</p>
<pre>
*vim-6.3.068 (25 Mar 2005)
25 Mar 2005; Ciaran McCreesh <ciaranm@gentoo.org> +vim-6.3.068.ebuild:
New release. Fixes bug #79981, bug #81289, bug #83383, bug #83416, bug
#83565, bug #85758, upstream patches up to 6.3.068.
22 Mar 2005; Aron Griffis <agriffis@gentoo.org> vim-6.3-r4.ebuild:
Stable on alpha
</pre>
<note>
If a <c>ChangeLog</c> file is not present in your current working directory,
then you should write a <c>ChangeLog</c> entry in the parent's directory
<c>ChangeLog</c> file.
</note>
<section>
<title>Writing correct ChangeLog messages</title>
<body>
<note>
It is <b>very</b> important that your <c>cvs commit</c> messages are
also informative to aid the QA team or architecture teams as well as
other developers if they are trying to troubleshoot issues which are
known to not have occured in previous versions of ebuilds, for
example. If your ChangeLog message is concise there is usually nothing
wrong with using it as the <c>cvs commit</c> message.
</note>
<p>
Your message should explain what specifically you changed and, if
relevant, why. You don't need to write an essay or even a complete
sentence (<c>ChangeLog</c> messages, however, are required to be in
'proper' English so no <c>fixed that bug kthx Bob</c> messages —
please do use punctuation), so long as it is easily understandable and
(preferably) greppable. Bad and good examples, all of which are based
upon real messages:
</p>
<ul>
<li><b>BAD:</b> Changed keywords</li>
<li><e>GOOD:</e> Added ~x86 keyword</li>
</ul>
<ul>
<li><b>BAD:</b> Stable</li>
<li><e>GOOD:</e> Stable on x86, sparc, mips</li>
</ul>
<ul>
<li><b>BAD:</b> Fix stuff</li>
<li><e>GOOD:</e> Fix USE=foo logic error</li>
</ul>
<ul>
<li><b>BAD:</b> .</li>
<li><e>GOOD:</e> Purge old ebuilds</li>
</ul>
<ul>
<li>
<b>BAD:</b> Who the fuck reads this anyway? (<b>Editor's note</b>:
No, seriously, this is a genuine example. Do <e>not</e> do
this...)
</li>
<li><e>GOOD:</e> Version bump to 0.5.1.</li>
</ul>
</body>
</section>
</body>
</chapter>
</guide>
|
GitWeb