documentation/0.16.0-SNAPSHOT/releasedocmaker/index.html - yetus - Git at Google

 <!---
   Licensed to the Apache Software Foundation (ASF) under one
   or more contributor license agreements.  See the NOTICE file
   distributed with this work for additional information
   regarding copyright ownership.  The ASF licenses this file
   to you under the Apache License, Version 2.0 (the
   "License"); you may not use this file except in compliance
   with the License.  You may obtain a copy of the License at

     http://www.apache.org/licenses/LICENSE-2.0

   Unless required by applicable law or agreed to in writing,
   software distributed under the License is distributed on an
   "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
   KIND, either express or implied.  See the License for the
   specific language governing permissions and limitations
   under the License.
 -->

 <html>
     <head>
         <meta charset="utf-8">
         <title>Apache Yetus</title>
         <meta name="viewport" content="width=device-width, initial-scale=1.0">
         <meta name="description" content="">
         <meta name="author" content="">

         <link href="../../../assets/css/bootstrap.css" rel="stylesheet">
         <link href="../../../assets/css/bootstrap-theme.css" rel="stylesheet">
         <link href="../../../assets/css/font-awesome.css" rel="stylesheet">

         <!-- JS -->
         <script type="text/javascript" src="../../../assets/js/jquery-2.1.4.min.js"></script>
         <script type="text/javascript" src="../../../assets/js/bootstrap.js"></script>
   </head>
     <body>

 <div class="navbar navbar-inverse navbar-static-top" role="navigation">
     <div class="container">
         <div class="navbar-header">
             <button type="button" class="navbar-toggle" data-toggle="collapse" data-target=".navbar-collapse">
                 <span class="sr-only">Toggle navigation</span>
                 <span class="icon-bar"></span>
                 <span class="icon-bar"></span>
                 <span class="icon-bar"></span>
             </button>
             <a class="img-responsive pull-left" href="/">
                 <img style="max-height: 40px; margin-top: 5px; margin-bottom: 5px;" src="../../../assets/img/yetus_logo.png" alt="Apache Yetus logo" />
             </a>
         </div>
         <div class="navbar-collapse collapse">
             <ul class="nav navbar-nav">
                 <li><a href="/downloads/">Downloads</a>
                 <li class="dropdown">
                     <a class="dropdown-toggle" data-toggle="dropdown" href="#">Documentation <span class="caret"></span></a>
                     <ul class="dropdown-menu" role="menu">
                       <li><a href="/documentation/0.13.0/">Docs for v0.13.0</a></li>
                       <li><a href="/documentation/0.14.1/">Docs for v0.14.1</a></li>
                       <li><a href="/documentation/0.15.0/">Docs for v0.15.0</a></li>
                       <li><a href="/documentation/in-progress/">In Progress Docs for Contributors</a>
                       </li>
                       <li><a href="/documentation/history/">History of the Project</a>
                       </li>
                     </ul>
                 </li>
                 <li class="dropdown">
                     <a class="dropdown-toggle" data-toggle="dropdown" href="#">Get Involved <span class="caret"></span></a>
                     <ul class="dropdown-menu" role="menu" aria-labelledby="drop1">
                         <li role="presentation"><a role="menuitem" tabindex="-1" href="/mailinglists"><i class="fa fa-commenting"></i> Mailing Lists</a>
                         </li>
                         <li role="presentation"><a role="menuitem" tabindex="-1" href="https://issues.apache.org/jira/browse/YETUS"><i class="fa fa-bug"></i> JIRA (Bugs)</a>
                         </li>
                         <li role="presentation"><a role="menuitem" tabindex="-1" href="https://gitbox.apache.org/repos/asf/yetus.git"><i class="fa fa-code"></i> Source (Apache)</a>
                         </li>
                         <li role="presentation"><a role="menuitem" tabindex="-1" href="https://github.com/apache/yetus"><i class="fa fa-github-alt"></i> Source (GitHub)</a>
                         </li>
                         <li role="presentation"><a role="menuitem" tabindex="-1" href="/contribute/"><i class="fa fa-code-fork"></i> Contributing</a>
                         </li>
                         <li role="presentation"><a role="menuitem" tabindex="-1" href="https://twitter.com/ApacheYetus"><i class="fa fa-twitter"></i> @ApacheYetus</a>
                         </li>
                     </ul>
                 </li>
                 <li>
                     <li class="dropdown">
                         <a class="dropdown-toggle" data-toggle="dropdown" href="#">Apache Software Foundation <b class="caret"></b></a>
                         <ul class="dropdown-menu" role="menu">
                             <li><a href="https://www.apache.org">Apache Homepage</a>
                             </li>
                             <li><a href="https://www.apache.org/licenses/">Apache License</a>
                             </li>
                             <li><a href="https://www.apache.org/foundation/sponsorship.html">Sponsorship</a>
                             </li>
                             <li><a href="https://www.apache.org/foundation/thanks.html">Thanks</a>
                             </li>
                             <li><a href="https://www.apache.org/security/">Security</a>
                             </li>
                         </ul>
                     </li>
                 </li>
             </ul>
         </div>
         <!--/.nav-collapse -->
     </div>
 </div>

       <div class="container">
         <!---
   Licensed to the Apache Software Foundation (ASF) under one
   or more contributor license agreements.  See the NOTICE file
   distributed with this work for additional information
   regarding copyright ownership.  The ASF licenses this file
   to you under the Apache License, Version 2.0 (the
   "License"); you may not use this file except in compliance
   with the License.  You may obtain a copy of the License at

     http://www.apache.org/licenses/LICENSE-2.0

   Unless required by applicable law or agreed to in writing,
   software distributed under the License is distributed on an
   "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
   KIND, either express or implied.  See the License for the
   specific language governing permissions and limitations
   under the License.
 -->

 <h1 id="releasedocmaker">releasedocmaker</h1>

 <!-- MarkdownTOC levels="1,2" autolink="true" indent="  " bullets="*" bracket="round" -->

 <ul>
   <li><a href="#purpose">Purpose</a></li>
   <li><a href="#requirements">Requirements</a></li>
   <li><a href="#basic-usage">Basic Usage</a></li>
   <li><a href="#authentication">Authentication</a></li>
   <li><a href="#changing-the-header">Changing the Header</a></li>
   <li><a href="#versioned-files-and-directories">Versioned Files and Directories</a></li>
   <li><a href="#multiple-versions">Multiple Versions</a></li>
   <li><a href="#unreleased-dates">Unreleased Dates</a></li>
   <li><a href="#sorted-output">Sorted Output</a>
     <ul>
       <li><a href="#resolution-date-base-sort">Resolution Date-base Sort</a></li>
       <li><a href="#issue-number-based-sort">Issue Number-based Sort</a></li>
     </ul>
   </li>
   <li><a href="#backward-incompatible-changes">Backward Incompatible Changes</a></li>
   <li><a href="#lint-mode">Lint Mode</a></li>
   <li><a href="#index-mode">Index Mode</a></li>
   <li><a href="#release-version">Release Version</a></li>
 </ul>

 <!-- /MarkdownTOC -->

 <h1 id="purpose">Purpose</h1>

 <p>Building changelog information in a form that is human digestible but still containing as much useful information is difficult.  Many attempts over the years have resulted in a variety of methods that projects use to solve this problem:</p>

 <ul>
   <li>JIRA-generated release notes from the "Release Notes" button</li>
   <li>Manually modified CHANGELOG file</li>
   <li>Processing git log information</li>
 </ul>

 <p>All of these methods have their pros and cons.  Some have issues with accuracy.  Some have issues with lack of details. None of these methods seem to cover all of the needs of many projects and are full of potential pitfalls.</p>

 <p>In order to solve these problems, <code>releasedocmaker</code> was written to automatically generate a changelog and release notes by querying Apache's JIRA instance.</p>

 <h1 id="requirements">Requirements</h1>

 <ul>
   <li>Python 3.8 with dateutil extension</li>
 </ul>

 <p>dateutil may be installed via pip:  <code>pip3 install python-dateutil</code></p>

 <h1 id="basic-usage">Basic Usage</h1>

 <p>Minimally, the name of the JIRA project and a version registered in JIRA must be provided:</p>

 <div class="highlight"><pre class="highlight shell"><code><span class="nv">$ </span>releasedocmaker <span class="nt">--project</span> <span class="o">(</span>project<span class="o">)</span> <span class="nt">--version</span> <span class="o">(</span>version<span class="o">)</span>
 </code></pre></div>
 <p>This will query Apache JIRA, generating two files in a directory named after the given version in an extended markdown format which can be processed by both mvn site and GitHub.</p>

 <ul>
   <li>CHANGELOG.md</li>
 </ul>

 <p>This is similar to the JIRA "Release Notes" button but is in tabular format and includes the priority, component, reporter, and contributor fields.  It also highlights Incompatible Changes so that readers know what to look out for when upgrading. The top of the file also includes the date that the version was marked as released in JIRA.</p>

 <ul>
   <li>RELEASENOTES.md</li>
 </ul>

 <p>If your JIRA project supports the release note field, this will contain any JIRA mentioned in the <code>CHANGELOG</code> that is either an incompatible change or has a release note associated with it.  If your JIRA project does not support the release notes field, this will be the description field.</p>

 <p>For example, to build the release documentation for HBase v1.2.0:</p>

 <div class="highlight"><pre class="highlight shell"><code><span class="nv">$ </span>releasedocmaker <span class="nt">--project</span> HBASE <span class="nt">--version</span> 1.2.0
 </code></pre></div>
 <p>By default, release notes are expected to be in plain text.  However, you can write them in markdown if you include a header at the top of your release note:</p>

 <div class="highlight"><pre class="highlight xml"><code><span class="c">&lt;!-- markdown --&gt;</span>
 remaining text
 </code></pre></div>
 <h1 id="authentication">Authentication</h1>

 <p><code>releasedocmaker</code> supports very simple Basic authentication.  This is accomplished by adding two environment variables to your shell environment:</p>

 <div class="highlight"><pre class="highlight shell"><code><span class="nv">RDM_JIRA_USERNAME</span><span class="o">=</span><span class="s1">'jirausername'</span>
 <span class="nv">RDM_JIRA_PASSWORD</span><span class="o">=</span><span class="s1">'jirapassword'</span>
 </code></pre></div>
 <p>These values will be added to all requests destined for the JIRA server.</p>

 <h1 id="changing-the-header">Changing the Header</h1>

 <p>By default, it will use a header that matches the project name.  But that is kind of ugly and the case may be wrong.  Luckily, the title can be changed:</p>

 <div class="highlight"><pre class="highlight shell"><code><span class="nv">$ </span>releasedocmaker <span class="nt">--project</span> HBASE <span class="nt">--version</span> 1.2.0 <span class="nt">--projecttitle</span> <span class="s2">"Apache HBase"</span>
 </code></pre></div>
 <p>Now instead of "HBASE", it will use "Apache HBase" for some titles and headers.</p>

 <h1 id="versioned-files-and-directories">Versioned Files and Directories</h1>

 <p>It is sometimes useful to create the <code>CHANGELOG</code> and <code>RELEASENOTES</code> with versions attached.  <code>releasedocmaker</code> supports both independently.</p>

 <div class="highlight"><pre class="highlight shell"><code><span class="nv">$ </span>releasedocmaker <span class="nt">--project</span> HBASE <span class="nt">--version</span> 1.2.0 <span class="nt">--fileversions</span>
 </code></pre></div>
 <p>This command line will now create <code>CHANGELOG.1.2.0.md</code> and <code>RELEASENOTES.1.2.0.md</code> files.</p>

 <div class="highlight"><pre class="highlight shell"><code><span class="nv">$ </span>releasedocmaker <span class="nt">--project</span> HBASE <span class="nt">--version</span> 1.2.0 <span class="nt">--dirversions</span>
 </code></pre></div>
 <p>This command line will now create a directory called 1.2.0 and inside will be the <code>CHANGELOG.md</code> and <code>RELEASENOTES.md</code> files.</p>

 <p>Using both at the same time…</p>

 <div class="highlight"><pre class="highlight shell"><code><span class="nv">$ </span>releasedocmaker <span class="nt">--project</span> HBASE <span class="nt">--version</span> 1.2.0 <span class="nt">--fileversions</span> <span class="nt">--dirversions</span>
 </code></pre></div>
 <p>… results in <code>1.2.0/CHANGELOG.1.2.0.md</code> and <code>1.2.0/RELEASENOTES.1.2.0.md</code> files.</p>

 <h1 id="multiple-versions">Multiple Versions</h1>

 <p>Using either <code>--dirversions</code> or <code>--fileversions</code> or both simultaneously, <code>releasedocmaker</code> can also generate multiple versions at once</p>

 <div class="highlight"><pre class="highlight shell"><code><span class="nv">$ </span>releasedocmaker <span class="nt">--project</span> HBASE <span class="nt">--version</span> 1.0.0 <span class="nt">--version</span> 1.2.0 <span class="nt">--dirversions</span>
 </code></pre></div>
 <p>This will create the files for versions 1.0.0 and versions 1.2.0 in their own directories.</p>

 <p>But what if the version numbers are not known?  <code>releasedocmaker</code> can also generate version data based upon ranges:</p>

 <div class="highlight"><pre class="highlight shell"><code><span class="nv">$ </span>releasedocmaker <span class="nt">--project</span> HBASE <span class="nt">--version</span> 1.0.0 <span class="nt">--version</span> 1.2.0 <span class="nt">--range</span> <span class="nt">--fileversions</span>
 </code></pre></div>
 <p>In this form, <code>releasedocmaker</code> will query JIRA, discover all versions that alphabetically appear to be between 1.0.0 and 1.2.0, inclusive, and generate all of the relative release documents.  This is especially useful when bootstrapping an existing project.</p>

 <h1 id="unreleased-dates">Unreleased Dates</h1>

 <p>For released versions, releasedocmaker will pull the date of the release from JIRA.  However, for unreleased versions it marks the release as "Unreleased". This can be inconvenient when actually building a release and wanting to include it inside the source package.</p>

 <p>The <code>--usetoday</code> option can be used to signify that instead of using Unreleased, <code>releasedocmaker</code> should use today's date.</p>

 <div class="highlight"><pre class="highlight shell"><code><span class="nv">$ </span>releasedocmaker <span class="nt">--project</span> HBASE <span class="nt">--version</span> 1.0.0 <span class="nt">--usetoday</span>
 </code></pre></div>
 <p>After using this option and release, don't forget to change JIRA's release date to match!</p>

 <h1 id="sorted-output">Sorted Output</h1>

 <p>Different projects may find one type of sort better than another, depending upon their needs.  <code>releasedocmaker</code> supports two types of sorts and each provides two different options in the direction for that sort.</p>

 <h2 id="resolution-date-base-sort">Resolution Date-base Sort</h2>

 <p>By default, <code>releasedocmaker</code> will sort the output based upon the resolution date of the issue starting with older resolutions.  This is the same as giving these options:</p>

 <div class="highlight"><pre class="highlight shell"><code><span class="nv">$ </span>releasedocmaker <span class="nt">--project</span> falcon <span class="nt">--version</span> 0.6 <span class="nt">--sorttype</span> resolutiondate <span class="nt">--sortorder</span> older
 </code></pre></div>
 <p>The order can be reversed so that newer issues appear on top by providing the 'newer' flag:</p>

 <div class="highlight"><pre class="highlight shell"><code><span class="nv">$ </span>releasedocmaker <span class="nt">--project</span> falcon <span class="nt">--version</span> 0.6 <span class="nt">--sorttype</span> resolutiondate <span class="nt">--sortorder</span> newer
 </code></pre></div>
 <p>In the case of multiple projects given on the command line, the projects will be interspersed.</p>

 <h2 id="issue-number-based-sort">Issue Number-based Sort</h2>

 <p>An alternative to the date-based sort is to sort based upon the issue id.  This may be accomplished via:</p>

 <div class="highlight"><pre class="highlight shell"><code><span class="nv">$ </span>releasedocmaker <span class="nt">--project</span> falcon <span class="nt">--version</span> 0.6 <span class="nt">--sorttype</span> issueid <span class="nt">--sortorder</span> asc
 </code></pre></div>
 <p>This will now sort by the issue id, listing them in lowest to highest (or ascending) order.</p>

 <p>The order may be reversed to list them in highest to lowest (or descending) order by providing the appropriate flag:</p>

 <div class="highlight"><pre class="highlight shell"><code><span class="nv">$ </span>releasedocmaker <span class="nt">--project</span> falcon <span class="nt">--version</span> 0.6 <span class="nt">--sorttype</span> issueid <span class="nt">--sortorder</span> desc
 </code></pre></div>
 <p>In the case of multiple projects given on the command line, the projects will be grouped and then sorted by issue id.</p>

 <h1 id="backward-incompatible-changes">Backward Incompatible Changes</h1>

 <p>To check if an issue is backward-incompatible the <code>releasedocmaker</code> script first checks the "Hadoop Flags" field in the<br />
 issue. If this field is found to be blank then it searches for the 'backward-incompatible' label. You can override the<br />
 default value for this label by using <code>--incompatiblelabel</code> option e.g.</p>

 <div class="highlight"><pre class="highlight shell"><code><span class="nv">$ </span>releasedocmaker <span class="nt">--project</span> falcon <span class="nt">--version</span> 0.6 <span class="nt">--incompatiblelabel</span> not-compatible
 </code></pre></div>
 <p>or equivalently using the shorter <code>-X</code> option</p>

 <div class="highlight"><pre class="highlight shell"><code><span class="nv">$ </span>releasedocmaker <span class="nt">--project</span> falcon <span class="nt">--version</span> 0.6 <span class="nt">-X</span> not-compatible
 </code></pre></div>
 <h1 id="lint-mode">Lint Mode</h1>

 <p>In order to ensure proper formatting while using mvn site, <code>releasedocmaker</code> puts in periods (.) for fields that are empty or unassigned.  This can be unsightly and not proper for any given project.  There are also other things, such as missing release notes for incompatible changes, that are less than desirable.</p>

 <p>In order to help release managers from having to scan through potentially large documents, <code>releasedocmaker</code> features a lint mode, triggered via <code>--lint</code>:</p>

 <div class="highlight"><pre class="highlight shell"><code><span class="nv">$ </span>releasedocmaker <span class="nt">--project</span> HBASE <span class="nt">--version</span> 1.0.0 <span class="nt">--lint</span>
 </code></pre></div>
 <p>This will do the normal JIRA querying, looking for items it considers problematic.  It will print the information to the screen and then exit with either success or failure, depending upon if any issues were discovered.</p>

 <h1 id="index-mode">Index Mode</h1>

 <p>There is basic support for an autoindexer.  It will create two files that contain links to all directories that have a major.minor*-style<br />
 version numbering system.<br />
 For example directories with names like 0.6, 1.2.2, 1.2alpha etc. will all be linked.</p>

 <ul>
   <li><code>index.md</code>: a file suitable for conversion to HTML via mvn site</li>
   <li><code>README.md</code>: a file suitable for display on Github and other Markdown rendering websites</li>
 </ul>

 <h1 id="release-version">Release Version</h1>

 <p>You can find the version of the <code>releasedocmaker</code> that you are using by giving the <code>-V</code> option. This may be helpful in finding documentation for the version you are using.</p>

 <div class="highlight"><pre class="highlight shell"><code><span class="nv">$ </span>releasedocmaker <span class="nt">-V</span>
 </code></pre></div>
     </div>

 <div class="container">
     <hr>
     <footer class="footer">
         <div class="row-fluid">
             <div class="span12 text-left">
               <div class="span12">
                 Copyright 2008-2023 <a href="https://www.apache.org/">Apache Software Foundation</a>. Licensed under the <a href="https://www.apache.org/licenses/">Apache License v2.0</a>. Apache Yetus and the Apache feather logo are trademarks of The Apache Software Foundation.
               </div>
             </div>

         </div>

     </footer>
 </div>

   </body>
 </html>
	<!---
	Licensed to the Apache Software Foundation (ASF) under one
	or more contributor license agreements. See the NOTICE file
	distributed with this work for additional information
	regarding copyright ownership. The ASF licenses this file
	to you under the Apache License, Version 2.0 (the
	"License"); you may not use this file except in compliance
	with the License. You may obtain a copy of the License at

	http://www.apache.org/licenses/LICENSE-2.0

	Unless required by applicable law or agreed to in writing,
	software distributed under the License is distributed on an
	"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
	KIND, either express or implied. See the License for the
	specific language governing permissions and limitations
	under the License.
	-->

	<html>
	<head>
	<meta charset="utf-8">
	<title>Apache Yetus</title>
	<meta name="viewport" content="width=device-width, initial-scale=1.0">
	<meta name="description" content="">
	<meta name="author" content="">

	<link href="../../../assets/css/bootstrap.css" rel="stylesheet">
	<link href="../../../assets/css/bootstrap-theme.css" rel="stylesheet">
	<link href="../../../assets/css/font-awesome.css" rel="stylesheet">

	<!-- JS -->
	<script type="text/javascript" src="../../../assets/js/jquery-2.1.4.min.js"></script>
	<script type="text/javascript" src="../../../assets/js/bootstrap.js"></script>
	</head>
	<body>

	<div class="navbar navbar-inverse navbar-static-top" role="navigation">
	<div class="container">
	<div class="navbar-header">
	<button type="button" class="navbar-toggle" data-toggle="collapse" data-target=".navbar-collapse">
	<span class="sr-only">Toggle navigation</span>
	<span class="icon-bar"></span>
	<span class="icon-bar"></span>
	<span class="icon-bar"></span>
	</button>
	<a class="img-responsive pull-left" href="/">
	<img style="max-height: 40px; margin-top: 5px; margin-bottom: 5px;" src="../../../assets/img/yetus_logo.png" alt="Apache Yetus logo" />
	</a>
	</div>
	<div class="navbar-collapse collapse">
	<ul class="nav navbar-nav">
	<li><a href="/downloads/">Downloads</a>
	<li class="dropdown">
	<a class="dropdown-toggle" data-toggle="dropdown" href="#">Documentation <span class="caret"></span></a>
	<ul class="dropdown-menu" role="menu">
	<li><a href="/documentation/0.13.0/">Docs for v0.13.0</a></li>
	<li><a href="/documentation/0.14.1/">Docs for v0.14.1</a></li>
	<li><a href="/documentation/0.15.0/">Docs for v0.15.0</a></li>
	<li><a href="/documentation/in-progress/">In Progress Docs for Contributors</a>
	</li>
	<li><a href="/documentation/history/">History of the Project</a>
	</li>
	</ul>
	</li>
	<li class="dropdown">
	<a class="dropdown-toggle" data-toggle="dropdown" href="#">Get Involved <span class="caret"></span></a>
	<ul class="dropdown-menu" role="menu" aria-labelledby="drop1">
	<li role="presentation"><a role="menuitem" tabindex="-1" href="/mailinglists"><i class="fa fa-commenting"></i> Mailing Lists</a>
	</li>
	<li role="presentation"><a role="menuitem" tabindex="-1" href="https://issues.apache.org/jira/browse/YETUS"><i class="fa fa-bug"></i> JIRA (Bugs)</a>
	</li>
	<li role="presentation"><a role="menuitem" tabindex="-1" href="https://gitbox.apache.org/repos/asf/yetus.git"><i class="fa fa-code"></i> Source (Apache)</a>
	</li>
	<li role="presentation"><a role="menuitem" tabindex="-1" href="https://github.com/apache/yetus"><i class="fa fa-github-alt"></i> Source (GitHub)</a>
	</li>
	<li role="presentation"><a role="menuitem" tabindex="-1" href="/contribute/"><i class="fa fa-code-fork"></i> Contributing</a>
	</li>
	<li role="presentation"><a role="menuitem" tabindex="-1" href="https://twitter.com/ApacheYetus"><i class="fa fa-twitter"></i> @ApacheYetus</a>
	</li>
	</ul>
	</li>
	<li>
	<li class="dropdown">
	<a class="dropdown-toggle" data-toggle="dropdown" href="#">Apache Software Foundation <b class="caret"></b></a>
	<ul class="dropdown-menu" role="menu">
	<li><a href="https://www.apache.org">Apache Homepage</a>
	</li>
	<li><a href="https://www.apache.org/licenses/">Apache License</a>
	</li>
	<li><a href="https://www.apache.org/foundation/sponsorship.html">Sponsorship</a>
	</li>
	<li><a href="https://www.apache.org/foundation/thanks.html">Thanks</a>
	</li>
	<li><a href="https://www.apache.org/security/">Security</a>
	</li>
	</ul>
	</li>
	</li>
	</ul>
	</div>
	<!--/.nav-collapse -->
	</div>
	</div>

	<div class="container">
	<!---
	Licensed to the Apache Software Foundation (ASF) under one
	or more contributor license agreements. See the NOTICE file
	distributed with this work for additional information
	regarding copyright ownership. The ASF licenses this file
	to you under the Apache License, Version 2.0 (the
	"License"); you may not use this file except in compliance
	with the License. You may obtain a copy of the License at

	http://www.apache.org/licenses/LICENSE-2.0

	Unless required by applicable law or agreed to in writing,
	software distributed under the License is distributed on an
	"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
	KIND, either express or implied. See the License for the
	specific language governing permissions and limitations
	under the License.
	-->

	<h1 id="releasedocmaker">releasedocmaker</h1>

	<!-- MarkdownTOC levels="1,2" autolink="true" indent=" " bullets="*" bracket="round" -->

	<ul>
	<li><a href="#purpose">Purpose</a></li>
	<li><a href="#requirements">Requirements</a></li>
	<li><a href="#basic-usage">Basic Usage</a></li>
	<li><a href="#authentication">Authentication</a></li>
	<li><a href="#changing-the-header">Changing the Header</a></li>
	<li><a href="#versioned-files-and-directories">Versioned Files and Directories</a></li>
	<li><a href="#multiple-versions">Multiple Versions</a></li>
	<li><a href="#unreleased-dates">Unreleased Dates</a></li>
	<li><a href="#sorted-output">Sorted Output</a>
	<ul>
	<li><a href="#resolution-date-base-sort">Resolution Date-base Sort</a></li>
	<li><a href="#issue-number-based-sort">Issue Number-based Sort</a></li>
	</ul>
	</li>
	<li><a href="#backward-incompatible-changes">Backward Incompatible Changes</a></li>
	<li><a href="#lint-mode">Lint Mode</a></li>
	<li><a href="#index-mode">Index Mode</a></li>
	<li><a href="#release-version">Release Version</a></li>
	</ul>

	<!-- /MarkdownTOC -->

	<h1 id="purpose">Purpose</h1>

	<p>Building changelog information in a form that is human digestible but still containing as much useful information is difficult. Many attempts over the years have resulted in a variety of methods that projects use to solve this problem:</p>

	<ul>
	<li>JIRA-generated release notes from the "Release Notes" button</li>
	<li>Manually modified CHANGELOG file</li>
	<li>Processing git log information</li>
	</ul>

	<p>All of these methods have their pros and cons. Some have issues with accuracy. Some have issues with lack of details. None of these methods seem to cover all of the needs of many projects and are full of potential pitfalls.</p>

	<p>In order to solve these problems, <code>releasedocmaker</code> was written to automatically generate a changelog and release notes by querying Apache's JIRA instance.</p>

	<h1 id="requirements">Requirements</h1>

	<ul>
	<li>Python 3.8 with dateutil extension</li>
	</ul>

	<p>dateutil may be installed via pip: <code>pip3 install python-dateutil</code></p>

	<h1 id="basic-usage">Basic Usage</h1>

	<p>Minimally, the name of the JIRA project and a version registered in JIRA must be provided:</p>

	<div class="highlight"><pre class="highlight shell"><code><span class="nv">$ </span>releasedocmaker <span class="nt">--project</span> <span class="o">(</span>project<span class="o">)</span> <span class="nt">--version</span> <span class="o">(</span>version<span class="o">)</span>
	</code></pre></div>
	<p>This will query Apache JIRA, generating two files in a directory named after the given version in an extended markdown format which can be processed by both mvn site and GitHub.</p>

	<ul>
	<li>CHANGELOG.md</li>
	</ul>

	<p>This is similar to the JIRA "Release Notes" button but is in tabular format and includes the priority, component, reporter, and contributor fields. It also highlights Incompatible Changes so that readers know what to look out for when upgrading. The top of the file also includes the date that the version was marked as released in JIRA.</p>

	<ul>
	<li>RELEASENOTES.md</li>
	</ul>

	<p>If your JIRA project supports the release note field, this will contain any JIRA mentioned in the <code>CHANGELOG</code> that is either an incompatible change or has a release note associated with it. If your JIRA project does not support the release notes field, this will be the description field.</p>

	<p>For example, to build the release documentation for HBase v1.2.0:</p>

	<div class="highlight"><pre class="highlight shell"><code><span class="nv">$ </span>releasedocmaker <span class="nt">--project</span> HBASE <span class="nt">--version</span> 1.2.0
	</code></pre></div>
	<p>By default, release notes are expected to be in plain text. However, you can write them in markdown if you include a header at the top of your release note:</p>

	<div class="highlight"><pre class="highlight xml"><code><span class="c"><!-- markdown --></span>
	remaining text
	</code></pre></div>
	<h1 id="authentication">Authentication</h1>

	<p><code>releasedocmaker</code> supports very simple Basic authentication. This is accomplished by adding two environment variables to your shell environment:</p>

	<div class="highlight"><pre class="highlight shell"><code><span class="nv">RDM_JIRA_USERNAME</span><span class="o">=</span><span class="s1">'jirausername'</span>
	<span class="nv">RDM_JIRA_PASSWORD</span><span class="o">=</span><span class="s1">'jirapassword'</span>
	</code></pre></div>
	<p>These values will be added to all requests destined for the JIRA server.</p>

	<h1 id="changing-the-header">Changing the Header</h1>

	<p>By default, it will use a header that matches the project name. But that is kind of ugly and the case may be wrong. Luckily, the title can be changed:</p>

	<div class="highlight"><pre class="highlight shell"><code><span class="nv">$ </span>releasedocmaker <span class="nt">--project</span> HBASE <span class="nt">--version</span> 1.2.0 <span class="nt">--projecttitle</span> <span class="s2">"Apache HBase"</span>
	</code></pre></div>
	<p>Now instead of "HBASE", it will use "Apache HBase" for some titles and headers.</p>

	<h1 id="versioned-files-and-directories">Versioned Files and Directories</h1>

	<p>It is sometimes useful to create the <code>CHANGELOG</code> and <code>RELEASENOTES</code> with versions attached. <code>releasedocmaker</code> supports both independently.</p>

	<div class="highlight"><pre class="highlight shell"><code><span class="nv">$ </span>releasedocmaker <span class="nt">--project</span> HBASE <span class="nt">--version</span> 1.2.0 <span class="nt">--fileversions</span>
	</code></pre></div>
	<p>This command line will now create <code>CHANGELOG.1.2.0.md</code> and <code>RELEASENOTES.1.2.0.md</code> files.</p>

	<div class="highlight"><pre class="highlight shell"><code><span class="nv">$ </span>releasedocmaker <span class="nt">--project</span> HBASE <span class="nt">--version</span> 1.2.0 <span class="nt">--dirversions</span>
	</code></pre></div>
	<p>This command line will now create a directory called 1.2.0 and inside will be the <code>CHANGELOG.md</code> and <code>RELEASENOTES.md</code> files.</p>

	<p>Using both at the same time…</p>

	<div class="highlight"><pre class="highlight shell"><code><span class="nv">$ </span>releasedocmaker <span class="nt">--project</span> HBASE <span class="nt">--version</span> 1.2.0 <span class="nt">--fileversions</span> <span class="nt">--dirversions</span>
	</code></pre></div>
	<p>… results in <code>1.2.0/CHANGELOG.1.2.0.md</code> and <code>1.2.0/RELEASENOTES.1.2.0.md</code> files.</p>

	<h1 id="multiple-versions">Multiple Versions</h1>

	<p>Using either <code>--dirversions</code> or <code>--fileversions</code> or both simultaneously, <code>releasedocmaker</code> can also generate multiple versions at once</p>

	<div class="highlight"><pre class="highlight shell"><code><span class="nv">$ </span>releasedocmaker <span class="nt">--project</span> HBASE <span class="nt">--version</span> 1.0.0 <span class="nt">--version</span> 1.2.0 <span class="nt">--dirversions</span>
	</code></pre></div>
	<p>This will create the files for versions 1.0.0 and versions 1.2.0 in their own directories.</p>

	<p>But what if the version numbers are not known? <code>releasedocmaker</code> can also generate version data based upon ranges:</p>

	<div class="highlight"><pre class="highlight shell"><code><span class="nv">$ </span>releasedocmaker <span class="nt">--project</span> HBASE <span class="nt">--version</span> 1.0.0 <span class="nt">--version</span> 1.2.0 <span class="nt">--range</span> <span class="nt">--fileversions</span>
	</code></pre></div>
	<p>In this form, <code>releasedocmaker</code> will query JIRA, discover all versions that alphabetically appear to be between 1.0.0 and 1.2.0, inclusive, and generate all of the relative release documents. This is especially useful when bootstrapping an existing project.</p>

	<h1 id="unreleased-dates">Unreleased Dates</h1>

	<p>For released versions, releasedocmaker will pull the date of the release from JIRA. However, for unreleased versions it marks the release as "Unreleased". This can be inconvenient when actually building a release and wanting to include it inside the source package.</p>

	<p>The <code>--usetoday</code> option can be used to signify that instead of using Unreleased, <code>releasedocmaker</code> should use today's date.</p>

	<div class="highlight"><pre class="highlight shell"><code><span class="nv">$ </span>releasedocmaker <span class="nt">--project</span> HBASE <span class="nt">--version</span> 1.0.0 <span class="nt">--usetoday</span>
	</code></pre></div>
	<p>After using this option and release, don't forget to change JIRA's release date to match!</p>

	<h1 id="sorted-output">Sorted Output</h1>

	<p>Different projects may find one type of sort better than another, depending upon their needs. <code>releasedocmaker</code> supports two types of sorts and each provides two different options in the direction for that sort.</p>

	<h2 id="resolution-date-base-sort">Resolution Date-base Sort</h2>

	<p>By default, <code>releasedocmaker</code> will sort the output based upon the resolution date of the issue starting with older resolutions. This is the same as giving these options:</p>

	<div class="highlight"><pre class="highlight shell"><code><span class="nv">$ </span>releasedocmaker <span class="nt">--project</span> falcon <span class="nt">--version</span> 0.6 <span class="nt">--sorttype</span> resolutiondate <span class="nt">--sortorder</span> older
	</code></pre></div>
	<p>The order can be reversed so that newer issues appear on top by providing the 'newer' flag:</p>

	<div class="highlight"><pre class="highlight shell"><code><span class="nv">$ </span>releasedocmaker <span class="nt">--project</span> falcon <span class="nt">--version</span> 0.6 <span class="nt">--sorttype</span> resolutiondate <span class="nt">--sortorder</span> newer
	</code></pre></div>
	<p>In the case of multiple projects given on the command line, the projects will be interspersed.</p>

	<h2 id="issue-number-based-sort">Issue Number-based Sort</h2>

	<p>An alternative to the date-based sort is to sort based upon the issue id. This may be accomplished via:</p>

	<div class="highlight"><pre class="highlight shell"><code><span class="nv">$ </span>releasedocmaker <span class="nt">--project</span> falcon <span class="nt">--version</span> 0.6 <span class="nt">--sorttype</span> issueid <span class="nt">--sortorder</span> asc
	</code></pre></div>
	<p>This will now sort by the issue id, listing them in lowest to highest (or ascending) order.</p>

	<p>The order may be reversed to list them in highest to lowest (or descending) order by providing the appropriate flag:</p>

	<div class="highlight"><pre class="highlight shell"><code><span class="nv">$ </span>releasedocmaker <span class="nt">--project</span> falcon <span class="nt">--version</span> 0.6 <span class="nt">--sorttype</span> issueid <span class="nt">--sortorder</span> desc
	</code></pre></div>
	<p>In the case of multiple projects given on the command line, the projects will be grouped and then sorted by issue id.</p>

	<h1 id="backward-incompatible-changes">Backward Incompatible Changes</h1>

	<p>To check if an issue is backward-incompatible the <code>releasedocmaker</code> script first checks the "Hadoop Flags" field in the<br />
	issue. If this field is found to be blank then it searches for the 'backward-incompatible' label. You can override the<br />
	default value for this label by using <code>--incompatiblelabel</code> option e.g.</p>

	<div class="highlight"><pre class="highlight shell"><code><span class="nv">$ </span>releasedocmaker <span class="nt">--project</span> falcon <span class="nt">--version</span> 0.6 <span class="nt">--incompatiblelabel</span> not-compatible
	</code></pre></div>
	<p>or equivalently using the shorter <code>-X</code> option</p>

	<div class="highlight"><pre class="highlight shell"><code><span class="nv">$ </span>releasedocmaker <span class="nt">--project</span> falcon <span class="nt">--version</span> 0.6 <span class="nt">-X</span> not-compatible
	</code></pre></div>
	<h1 id="lint-mode">Lint Mode</h1>

	<p>In order to ensure proper formatting while using mvn site, <code>releasedocmaker</code> puts in periods (.) for fields that are empty or unassigned. This can be unsightly and not proper for any given project. There are also other things, such as missing release notes for incompatible changes, that are less than desirable.</p>

	<p>In order to help release managers from having to scan through potentially large documents, <code>releasedocmaker</code> features a lint mode, triggered via <code>--lint</code>:</p>

	<div class="highlight"><pre class="highlight shell"><code><span class="nv">$ </span>releasedocmaker <span class="nt">--project</span> HBASE <span class="nt">--version</span> 1.0.0 <span class="nt">--lint</span>
	</code></pre></div>
	<p>This will do the normal JIRA querying, looking for items it considers problematic. It will print the information to the screen and then exit with either success or failure, depending upon if any issues were discovered.</p>

	<h1 id="index-mode">Index Mode</h1>

	<p>There is basic support for an autoindexer. It will create two files that contain links to all directories that have a major.minor*-style<br />
	version numbering system.<br />
	For example directories with names like 0.6, 1.2.2, 1.2alpha etc. will all be linked.</p>

	<ul>
	<li><code>index.md</code>: a file suitable for conversion to HTML via mvn site</li>
	<li><code>README.md</code>: a file suitable for display on Github and other Markdown rendering websites</li>
	</ul>

	<h1 id="release-version">Release Version</h1>

	<p>You can find the version of the <code>releasedocmaker</code> that you are using by giving the <code>-V</code> option. This may be helpful in finding documentation for the version you are using.</p>

	<div class="highlight"><pre class="highlight shell"><code><span class="nv">$ </span>releasedocmaker <span class="nt">-V</span>
	</code></pre></div>
	</div>

	<div class="container">
	<hr>
	<footer class="footer">
	<div class="row-fluid">
	<div class="span12 text-left">
	<div class="span12">
	Copyright 2008-2023 <a href="https://www.apache.org/">Apache Software Foundation</a>. Licensed under the <a href="https://www.apache.org/licenses/">Apache License v2.0</a>. Apache Yetus and the Apache feather logo are trademarks of The Apache Software Foundation.
	</div>
	</div>

	</div>

	</footer>
	</div>

	</body>
	</html>