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