| 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><REV></var></span></kbd></td> |
| 121 |
</tr> |
| 122 |
<tr><td> </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> |