Debian Codegraph @

doc/html/ext-releasenotes.html

raw
1 <?xml version="1.0" encoding="utf-8"?>
2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
3 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
4 <head>
5 <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
6 <meta name="generator" content="Docutils 0.21.2: https://docutils.sourceforge.io/" />
7 <title>releasenotes</title>
8 <link rel="stylesheet" href="../style.css" type="text/css" />
9 </head>
10 <body>
11 <div class="document" id="releasenotes">
12 <span id="ext-releasenotes"></span>
13 <h1 class="title">releasenotes</h1>
14
15 <div class="contents htmlonly topic" id="contents">
16 <p class="topic-title"><a class="reference internal" href="#top">Contents</a></p>
17 <ul class="simple">
18 <li><a class="reference internal" href="#description" id="toc-entry-1">Description</a></li>
19 <li><a class="reference internal" href="#commands" id="toc-entry-2">Commands</a><ul>
20 <li><a class="reference internal" href="#change-navigation" id="toc-entry-3">Change navigation</a></li>
21 </ul>
22 </li>
23 </ul>
24 </div>
25 <p>generate release notes from commit messages (EXPERIMENTAL)</p>
26 <div class="section" id="description">
27 <h1><a class="toc-backref" href="#contents">Description</a></h1>
28 <p>It is common to maintain files detailing changes in a project between
29 releases. Maintaining these files can be difficult and time consuming.
30 The <a class="reference external" href="hg-releasenotes.html"><tt class="docutils literal">hg releasenotes</tt></a> command provided by this extension makes the
31 process simpler by automating it.</p>
32 </div>
33 <div class="section" id="commands">
34 <h1><a class="toc-backref" href="#contents">Commands</a></h1>
35 <div class="section" id="change-navigation">
36 <h2><a class="toc-backref" href="#contents">Change navigation</a></h2>
37 <div class="section" id="releasenotes-1">
38 <h3>releasenotes</h3>
39 <p>parse release notes from commit messages into an output file:</p>
40 <pre class="literal-block">
41 hg releasenotes [-r REV] [-c] FILE
42 </pre>
43 <p>Given an output file and set of revisions, this command will parse commit
44 messages for release notes then add them to the output file.</p>
45 <p>Release notes are defined in commit messages as ReStructuredText
46 directives. These have the form:</p>
47 <pre class="literal-block">
48 .. directive:: title
49
50 content
51 </pre>
52 <p>Each <tt class="docutils literal">directive</tt> maps to an output section in a generated release notes
53 file, which itself is ReStructuredText. For example, the <tt class="docutils literal">.. feature::</tt>
54 directive would map to a <tt class="docutils literal">New Features</tt> section.</p>
55 <p>Release note directives can be either short-form or long-form. In short-
56 form, <tt class="docutils literal">title</tt> is omitted and the release note is rendered as a bullet
57 list. In long form, a sub-section with the title <tt class="docutils literal">title</tt> is added to the
58 section.</p>
59 <p>The <tt class="docutils literal">FILE</tt> argument controls the output file to write gathered release
60 notes to. The format of the file is:</p>
61 <pre class="literal-block">
62 Section 1
63 =========
64
65 ...
66
67 Section 2
68 =========
69
70 ...
71 </pre>
72 <p>Only sections with defined release notes are emitted.</p>
73 <p>If a section only has short-form notes, it will consist of bullet list:</p>
74 <pre class="literal-block">
75 Section
76 =======
77
78 * Release note 1
79 * Release note 2
80 </pre>
81 <p>If a section has long-form notes, sub-sections will be emitted:</p>
82 <pre class="literal-block">
83 Section
84 =======
85
86 Note 1 Title
87 ------------
88
89 Description of the first long-form note.
90
91 Note 2 Title
92 ------------
93
94 Description of the second long-form note.
95 </pre>
96 <p>If the <tt class="docutils literal">FILE</tt> argument points to an existing file, that file will be
97 parsed for release notes having the format that would be generated by this
98 command. The notes from the processed commit messages will be <em>merged</em>
99 into this parsed set.</p>
100 <p>During release notes merging:</p>
101 <ul class="simple">
102 <li>Duplicate items are automatically ignored</li>
103 <li>Items that are different are automatically ignored if the similarity is
104 greater than a threshold.</li>
105 </ul>
106 <p>This means that the release notes file can be updated independently from
107 this command and changes should not be lost when running this command on
108 that file. A particular use case for this is to tweak the wording of a
109 release note after it has been added to the release notes file.</p>
110 <p>The -c/--check option checks the commit message for invalid admonitions.</p>
111 <p>The -l/--list option, presents the user with a list of existing available
112 admonitions along with their title. This also includes the custom
113 admonitions (if any).</p>
114 <p>Options:</p>
115 <table class="docutils option-list" frame="void" rules="none">
116 <col class="option" />
117 <col class="description" />
118 <tbody valign="top">
119 <tr><td class="option-group" colspan="2">
120 <kbd><span class="option">-r</span>, <span class="option">--rev <var>&lt;REV&gt;</var></span></kbd></td>
121 </tr>
122 <tr><td>&nbsp;</td><td>revisions to process for release notes</td></tr>
123 <tr><td class="option-group">
124 <kbd><span class="option">-c</span>, <span class="option">--check</span></kbd></td>
125 <td>checks for validity of admonitions (if any)</td></tr>
126 <tr><td class="option-group">
127 <kbd><span class="option">-l</span>, <span class="option">--list</span></kbd></td>
128 <td>list the available admonitions with their title</td></tr>
129 </tbody>
130 </table>
131 </div>
132 </div>
133 </div>
134 </div>
135 </body>
136 </html>