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
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
|
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Docutils 0.21.2: https://docutils.sourceforge.io/" />
<title>releasenotes</title>
<link rel="stylesheet" href="../style.css" type="text/css" />
</head>
<body>
<div class="document" id="releasenotes">
<span id="ext-releasenotes"></span>
<h1 class="title">releasenotes</h1>
<div class="contents htmlonly topic" id="contents">
<p class="topic-title"><a class="reference internal" href="#top">Contents</a></p>
<ul class="simple">
<li><a class="reference internal" href="#description" id="toc-entry-1">Description</a></li>
<li><a class="reference internal" href="#commands" id="toc-entry-2">Commands</a><ul>
<li><a class="reference internal" href="#change-navigation" id="toc-entry-3">Change navigation</a></li>
</ul>
</li>
</ul>
</div>
<p>generate release notes from commit messages (EXPERIMENTAL)</p>
<div class="section" id="description">
<h1><a class="toc-backref" href="#contents">Description</a></h1>
<p>It is common to maintain files detailing changes in a project between
releases. Maintaining these files can be difficult and time consuming.
The <a class="reference external" href="hg-releasenotes.html"><tt class="docutils literal">hg releasenotes</tt></a> command provided by this extension makes the
process simpler by automating it.</p>
</div>
<div class="section" id="commands">
<h1><a class="toc-backref" href="#contents">Commands</a></h1>
<div class="section" id="change-navigation">
<h2><a class="toc-backref" href="#contents">Change navigation</a></h2>
<div class="section" id="releasenotes-1">
<h3>releasenotes</h3>
<p>parse release notes from commit messages into an output file:</p>
<pre class="literal-block">
hg releasenotes [-r REV] [-c] FILE
</pre>
<p>Given an output file and set of revisions, this command will parse commit
messages for release notes then add them to the output file.</p>
<p>Release notes are defined in commit messages as ReStructuredText
directives. These have the form:</p>
<pre class="literal-block">
.. directive:: title
content
</pre>
<p>Each <tt class="docutils literal">directive</tt> maps to an output section in a generated release notes
file, which itself is ReStructuredText. For example, the <tt class="docutils literal">.. feature::</tt>
directive would map to a <tt class="docutils literal">New Features</tt> section.</p>
<p>Release note directives can be either short-form or long-form. In short-
form, <tt class="docutils literal">title</tt> is omitted and the release note is rendered as a bullet
list. In long form, a sub-section with the title <tt class="docutils literal">title</tt> is added to the
section.</p>
<p>The <tt class="docutils literal">FILE</tt> argument controls the output file to write gathered release
notes to. The format of the file is:</p>
<pre class="literal-block">
Section 1
=========
...
Section 2
=========
...
</pre>
<p>Only sections with defined release notes are emitted.</p>
<p>If a section only has short-form notes, it will consist of bullet list:</p>
<pre class="literal-block">
Section
=======
* Release note 1
* Release note 2
</pre>
<p>If a section has long-form notes, sub-sections will be emitted:</p>
<pre class="literal-block">
Section
=======
Note 1 Title
------------
Description of the first long-form note.
Note 2 Title
------------
Description of the second long-form note.
</pre>
<p>If the <tt class="docutils literal">FILE</tt> argument points to an existing file, that file will be
parsed for release notes having the format that would be generated by this
command. The notes from the processed commit messages will be <em>merged</em>
into this parsed set.</p>
<p>During release notes merging:</p>
<ul class="simple">
<li>Duplicate items are automatically ignored</li>
<li>Items that are different are automatically ignored if the similarity is
greater than a threshold.</li>
</ul>
<p>This means that the release notes file can be updated independently from
this command and changes should not be lost when running this command on
that file. A particular use case for this is to tweak the wording of a
release note after it has been added to the release notes file.</p>
<p>The -c/--check option checks the commit message for invalid admonitions.</p>
<p>The -l/--list option, presents the user with a list of existing available
admonitions along with their title. This also includes the custom
admonitions (if any).</p>
<p>Options:</p>
<table class="docutils option-list" frame="void" rules="none">
<col class="option" />
<col class="description" />
<tbody valign="top">
<tr><td class="option-group" colspan="2">
<kbd><span class="option">-r</span>, <span class="option">--rev <var><REV></var></span></kbd></td>
</tr>
<tr><td> </td><td>revisions to process for release notes</td></tr>
<tr><td class="option-group">
<kbd><span class="option">-c</span>, <span class="option">--check</span></kbd></td>
<td>checks for validity of admonitions (if any)</td></tr>
<tr><td class="option-group">
<kbd><span class="option">-l</span>, <span class="option">--list</span></kbd></td>
<td>list the available admonitions with their title</td></tr>
</tbody>
</table>
</div>
</div>
</div>
</div>
</body>
</html>
|
