blob: 4fe86ae945dff16da44408aa30ee27ebf13ac1b4 [file] [log] [blame]
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Making a model release - Apache OpenNLP</title>
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1">
<meta name="color-scheme" content="dark light">
<meta name="description" content="Apache OpenNLP is a machine learning based toolkit for the processing of natural language text." />
<meta name="author" content="The Apache OpenNLP Team" />
<meta name="keywords" content="java, natural language processing, nlp, apache, open source, web site" />
<meta name="generator" content="JBake"/>
<!-- RSS Feed -->
<link rel="alternate" type="application/rss+xml" title="RSS" href="/feed.xml" />
<!-- Favicon -->
<link rel="apple-touch-icon" sizes="57x57" href="/apple-icon-57x57.png">
<link rel="apple-touch-icon" sizes="60x60" href="/apple-icon-60x60.png">
<link rel="apple-touch-icon" sizes="72x72" href="/apple-icon-72x72.png">
<link rel="apple-touch-icon" sizes="76x76" href="/apple-icon-76x76.png">
<link rel="apple-touch-icon" sizes="114x114" href="/apple-icon-114x114.png">
<link rel="apple-touch-icon" sizes="120x120" href="/apple-icon-120x120.png">
<link rel="apple-touch-icon" sizes="144x144" href="/apple-icon-144x144.png">
<link rel="apple-touch-icon" sizes="152x152" href="/apple-icon-152x152.png">
<link rel="apple-touch-icon" sizes="180x180" href="/apple-icon-180x180.png">
<link rel="icon" type="image/png" sizes="192x192" href="/android-icon-192x192.png">
<link rel="icon" type="image/png" sizes="32x32" href="/favicon-32x32.png">
<link rel="icon" type="image/png" sizes="96x96" href="/favicon-96x96.png">
<link rel="icon" type="image/png" sizes="16x16" href="/favicon-16x16.png">
<link rel="manifest" href="/manifest.json">
<meta name="msapplication-TileColor" content="#ffffff">
<meta name="msapplication-TileImage" content="/ms-icon-144x144.png">
<meta name="theme-color" content="#ffffff">
<!-- The styles -->
<link href="/css/bootstrap.min.css" rel="stylesheet">
<link href="/css/font-awesome.min.css" rel="stylesheet">
<link href="/css/asciidoctor.css" rel="stylesheet">
<link href="/css/prettify.css" rel="stylesheet">
<link href="/css/custom-style.css" rel="stylesheet">
<link href="/css/scheme-light.css" rel="stylesheet">
<link href="/css/scheme-dark.css" rel="stylesheet">
<!-- HTML5 shim, for IE6-8 support of HTML5 elements -->
<!--[if lt IE 9]>
<script src="/js/html5shiv.js"></script>
<![endif]-->
</head>
<body onload="prettyPrint()">
<span class="visible-lg">
<a href="https://github.com/apache/opennlp"><img style="z-index: 9999; position: absolute; top: 0; right: 0; border: 0;" src="/img/fork-me-on-github.png" alt="Fork me on GitHub" data-canonical-src="https://s3.amazonaws.com/github/ribbons/forkme_right_darkblue_121621.png"></a>
</span>
<nav class="navbar navbar-default">
<div class="container">
<div class="navbar-header">
<button type="button" class="navbar-toggle collapsed" data-toggle="collapse" data-target="#navbar-items" aria-expanded="false">
<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="navbar-brand" href="/">
<img alt="Brand" src="/img/opennlp-navbar-logo.png" class="img-responsive" width="100px" style="position: relative; top: -3px;">
</a>
</div>
<div class="collapse navbar-collapse" id="navbar-items">
<ul class="nav navbar-nav">
<li>
<a href="/"><span class="glyphicon glyphicon-home"></span> Home</a>
</li>
<li class="dropdown">
<a href="#" class="dropdown-toggle" data-toggle="dropdown"><span class="glyphicon glyphicon-download-alt"></span> Download <b class="caret"></b></a>
<ul class="dropdown-menu">
<li><a href="/download.html">OpenNLP Releases</a></li>
<li><a href="/models.html">OpenNLP Models</a></li>
<li><a href="/maven-dependency.html">Maven Integration</a></li>
<li><a href="/gradle-dependency.html">Gradle Integration</a></li>
</ul>
</li>
<li class="dropdown">
<a href="#" class="dropdown-toggle" data-toggle="dropdown"><span class="glyphicon glyphicon-flag"></span> General <b class="caret"></b></a>
<ul class="dropdown-menu">
<li><a href="/news/">News</a></li>
<li><a href="https://blogsarchive.apache.org/#opennlp" target="_blank">Blog</a></li>
<li><a href="/mailing-lists.html">Mailing Lists</a></li>
<li><a href="https://issues.apache.org/jira/browse/OPENNLP" target="_blank">Issue tracker</a></li>
<li><a href="/books-tutorials-and-talks.html">Books, Tutorials and Talks</a></li>
<li><a href="/powered-by-opennlp.html">Powered by Apache OpenNLP</a></li>
</ul>
</li>
<li class="dropdown">
<a href="#" class="dropdown-toggle" data-toggle="dropdown"><span class="glyphicon glyphicon-book"></span> Documentation <b class="caret"></b></a>
<ul class="dropdown-menu">
<li><a href="/docs/">Manual and Javadocs</a></li>
<li><a href="/faq.html">FAQ</a></li>
<li><a href="https://cwiki.apache.org/OPENNLP" target="_blank">Wiki</a></li>
</ul>
</li>
<li class="dropdown">
<a href="#" class="dropdown-toggle" data-toggle="dropdown"><span class="glyphicon glyphicon-console"></span> Development <b class="caret"></b></a>
<ul class="dropdown-menu">
<li><a href="/get-involved.html">Get Involved</a></li>
<li><a href="/source-code.html">Source Code</a></li>
<li><a href="/using-git.html">Using Git</a></li>
<li><a href="/building.html">Building</a></li>
<li><a href="/code-conventions.html">Code Conventions</a></li>
<li><a href="/release.html">Release</a></li>
<li><a href="/release-model.html">Release Models</a></li>
<li><a href="/team.html">Project Team</a></li>
</ul>
</li>
</ul>
<ul class="nav navbar-nav navbar-right">
<li class="dropdown">
<a href="#" class="dropdown-toggle" data-toggle="dropdown"><span class="glyphicon glyphicon-leaf"></span> ASF <b class="caret"></b></a>
<ul class="dropdown-menu">
<li><a href="https://www.apache.org/">The Apache Software Foundation</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>
<li><a href="https://www.apache.org/foundation/sponsorship.html">Become a Sponsor</a></li>
</ul>
</li>
</ul>
</div><!-- /.navbar-collapse -->
</div><!-- /.container-fluid -->
</nav>
<div class="container">
<h1 class="title">Making a model release</h1>
<div class="sect1">
<h2 id="release_preparation">Release Preparation</h2>
<div class="sectionbody">
<div class="ulist">
<ul>
<li>
<p>Elect a release manager.</p>
</li>
<li>
<p>Create a ticket for a new model release in <a href="https://issues.apache.org/jira/browse/OPENNLP" target="_blank" rel="noopener">JIRA</a>. If you do not have permission to do so just ask to be given permissions on the mailing list.</p>
</li>
</ul>
</div>
</div>
</div>
<div class="sect1">
<h2 id="steps_for_the_release_manager">Steps for the Release Manager</h2>
<div class="sectionbody">
<div class="paragraph">
<p>The following steps need only to be performed once.</p>
</div>
<div class="ulist">
<ul>
<li>
<p>Make sure you have your PGP key added to <a href="https://dist.apache.org/repos/dist/release/opennlp/KEYS" class="bare" target="_blank" rel="noopener">https://dist.apache.org/repos/dist/release/opennlp/KEYS</a> via SVN
If the key isn&#8217;t contained in this file, add your PGP key to the KEYS file:</p>
<div class="listingblock">
<div class="content">
<pre>Examples of adding your key to this file:
pgp -kxa &lt;your name&gt; and append it to this file.
(pgpk -ll &lt;your name&gt; &amp;&amp; pgpk -xa &lt;your name&gt;) &gt;&gt; this file.
(gpg --list-sigs &lt;your name&gt;
&amp;&amp; gpg --armor --export &lt;your name&gt;) &gt;&gt; this file.</pre>
</div>
</div>
</li>
<li>
<p>In a local temp folder, svn checkout the OpenNLP artifacts and update the KEYS file</p>
<div class="listingblock">
<div class="content">
<pre>svn co https://dist.apache.org/repos/dist/release/opennlp/
svn commit -m "Added Key for &lt;name&gt;" KEYS</pre>
</div>
</div>
</li>
<li>
<p>Make sure you have your PGP key&#8217;s password.</p>
</li>
</ul>
</div>
</div>
</div>
<div class="sect1">
<h2 id="release_steps">Release Steps</h2>
<div class="sectionbody">
<div class="ulist">
<ul>
<li>
<p>Train the models</p>
</li>
<li>
<p>Make sure to save the evaluation log for every model (adhere to the naming conventions, see below).</p>
</li>
<li>
<p>ZIP the evaluation logs.</p>
</li>
</ul>
</div>
<div class="sect2">
<h3 id="successful_model_release_preparation">Successful Model Release Preparation</h3>
<div class="sect3">
<h4 id="perform_the_model_release">Perform the Model Release</h4>
<div class="ulist">
<ul>
<li>
<p>Create sha512 checksums</p>
<div class="listingblock">
<div class="content">
<pre># cd to model location
for f in *; do sha512sum "$f" &gt; "$f.sha512"; done</pre>
</div>
</div>
</li>
<li>
<p>Create PGP signatures, see <a href="https://infra.apache.org/release-signing.html" target="_blank" rel="noopener">for details</a>.
If you have multiple keys on your system, you might need to use <code>-u</code> to select the signing key.</p>
<div class="listingblock">
<div class="content">
<pre># cd to model location
# create asc signatures for model files
for f in *.bin; do
gpg --armor --output $f.asc --detach-sig $f
done
# create asc signature for evaluation logs
for f in *.zip; do
gpg --armor --output $f.asc --detach-sig $f
done</pre>
</div>
</div>
</li>
<li>
<p>Add README, NOTICE, LICENSE and CHANGES (if any)</p>
</li>
<li>
<p>Create a folder in <code>dist/dev/models</code> in SVN</p>
<div class="listingblock">
<div class="content">
<pre>svn co https://dist.apache.org/repos/dist/dev/opennlp/ dist-dev
# check if the KEYS file contains your key, if not, update it
# copy the models and signatures to dist-dev/models/&lt;MODEL_TYPE&gt;-&lt;MODEL_VERSION&gt;
svn commit --username &lt;username&gt; -m "Adding Release Candidate for OpenNLP Models &lt;version&gt;"</pre>
</div>
</div>
</li>
</ul>
</div>
<div class="paragraph">
<p>Check the dist/dev folder and if all looks well, open a VOTE but do <strong>not</strong> move the files to dist/release at this time.</p>
</div>
<div class="paragraph">
<p>Make sure to adhere to the model naming conventions.</p>
</div>
</div>
<div class="sect3">
<h4 id="model_naming_conventions">Model Naming Conventions</h4>
<div class="ulist">
<ul>
<li>
<p>The filenames of each model signify the model language, type, <a href="https://universaldependencies.org/" target="_blank" rel="noopener">Universal Dependency training data</a> used, and version numbers.</p>
</li>
<li>
<p>The filename format is <code>opennlp-[iso-language-code]-ud-[corpus]-[model-type]-[model-version]-[opennlp-version-used-for-training].bin</code>.</p>
</li>
<li>
<p>The evaluation logs must be zipped and adhere to the following format: <code>opennlp-training-eval-logs-[model-version]-[opennlp-version-used-for-training].zip</code>. It contains the evaluation logs for trained models.</p>
</li>
<li>
<p>For example, the model file <code>opennlp-de-ud-gsd-pos-1.0-1.9.3</code> is German language, trained on the UD GSD corpus, and is a parts-of-speech model. It is version 1.0 of the model, and it was trained using OpenNLP 1.9.3.</p>
</li>
</ul>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<div class="title">Note</div>
</td>
<td class="content">
If other training data is used, the abbreviation <code>ud</code> needs to be adjusted!
</td>
</tr>
</table>
</div>
</div>
<div class="sect3">
<h4 id="check_the_model_release_artifacts">Check the Model Release Artifacts</h4>
<div class="paragraph">
<p>Perform basic checks against the release binary:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>Check signature of generated artifacts.</p>
</li>
<li>
<p>Check presence and appropriateness of <code>LICENSE</code>, <code>NOTICE</code>, and <code>README</code> files.</p>
</li>
</ul>
</div>
</div>
<div class="sect3">
<h4 id="create_a_vote_thread">Create a VOTE Thread</h4>
<div class="ulist">
<ul>
<li>
<p>Notify the developer mailing list of a new model vote. Be sure to replace all values in <code>[]</code> with the appropriate values.</p>
<div class="paragraph">
<p><em>Message Subject: [VOTE] Apache OpenNLP Models [version] Release Candidate</em></p>
</div>
<div class="listingblock">
<div class="content">
<pre>Hi folks,
I have posted a [Nth] release candidate for the Apache OpenNLP Models [UMODEL_VERSION] release and it is ready for testing.
The models can be downloaded from: https://dist.apache.org/repos/dist/dev/opennlp/&lt;MODEL_TYPE&gt;-&lt;MODEL_VERSION&gt;
The evaluation logs can be downloaded from https://dist.apache.org/repos/dist/dev/opennlp/&lt;MODEL_TYPE&gt;-&lt;MODEL_VERSION&gt;/opennlp-training-eval-logs-&lt;MODEL_VERSION&gt;-&lt;OPENNLP_VERSION&gt;.zip
The models were trained with Apache OpenNLP [VERSION] tag.
The release was made using the OpenNLP release process, documented on the website:
https://opennlp.apache.org/release-model.html
Please vote on releasing these models as Apache OpenNLP Models [MODEL_VERSION]. The vote is open for at least the next 72 hours.
Only votes from OpenNLP PMC are binding, but everyone is welcome to check the model release candidate and vote.
The vote passes if at least three binding +1 votes are cast.
[ ] +1 Release the models as Apache OpenNLP Models [MODEL_VERSION]
[ ] +0 meh, don't care
[ ] -1 Do not release the models because of ${showstopper}
Thanks!</pre>
</div>
</div>
</li>
</ul>
</div>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="after_a_successful_vote">After a Successful Vote</h2>
<div class="sectionbody">
<div class="paragraph">
<p>The vote is successful if at least 3 <em>+1</em> votes are received from OpenNLP PMC members after a minimum of 72 hours of sending the vote email.
Acknowledge the voting results on the mailing list in the VOTE thread.</p>
</div>
<div class="sect2">
<h3 id="commit_distribution_to_svn">Commit Distribution to SVN</h3>
<div class="paragraph">
<p>Commit the distribution via SVN to <a href="https://dist.apache.org/repos/dist/release" class="bare">https://dist.apache.org/repos/dist/release</a>:</p>
</div>
<div class="listingblock">
<div class="content">
<pre>svn co https://dist.apache.org/repos/dist/release/opennlp/ dist
# check if the KEYS file contains your key, if not, update it
# move the files from dev/models/&lt;MODEL_TYPE&gt;-&lt;MODEL_VERSION&gt; to dist/models/&lt;MODEL_TYPE&gt;-&lt;MODEL_VERSION&gt;
svn commit --username &lt;username&gt; -m "Adding OpenNLP Models &lt;version&gt;"</pre>
</div>
</div>
</div>
<div class="sect2">
<h3 id="delete_old_model_releases">Delete Old Model Release(s)</h3>
<div class="paragraph">
<p>To reduce the load on the ASF mirrors, projects are required to delete old releases (see <a href="https://www.apache.org/legal/release-policy.html#when-to-archive" class="bare">https://www.apache.org/legal/release-policy.html#when-to-archive</a>).</p>
</div>
<div class="paragraph">
<p>Remove the old model release from SVN under <a href="https://dist.apache.org/repos/dist/release/opennlp/models/" class="bare">https://dist.apache.org/repos/dist/release/opennlp/models/</a>. They are still contained in the archives.</p>
</div>
</div>
<div class="sect2">
<h3 id="update_the_website">Update the Website</h3>
<div class="paragraph">
<p>Update the <a href="https://opennlp.apache.org/models.html" target="_blank" rel="noopener">website</a> once the new version appears in the Apache download mirrors (keep checking <a href="https://www.apache.org/dyn/closer.cgi/opennlp/models/" class="bare" target="_blank" rel="noopener">https://www.apache.org/dyn/closer.cgi/opennlp/models/</a> until you see something).</p>
</div>
<div class="sect3">
<h4 id="add_news_item">Add News Item</h4>
<div class="ulist">
<ul>
<li>
<p>Add a news item in <code>news/model-{model-type}-{xyz}.ad</code> by copying the adjusted content:</p>
<div class="listingblock">
<div class="content">
<pre>= &lt;MODEL_TYPE&gt; Models for Apache OpenNLP released
Apache OpenNLP
2022-01-03
:jbake-type: post
:jbake-tags: community
:jbake-status: published
:category: news
:idprefix:
The Apache OpenNLP library is a machine learning based toolkit for the processing of natural language text.
The Apache OpenNLP team is pleased to announce the release of &lt;MODEL_TYPE&gt;-&lt;MODEL_VERSION&gt; for Apache OpenNLP &lt;OPENNLP_VERSION&gt;.
The models can &lt;ADD_SUMMARY_HERE&gt;
Apache OpenNLP model and reports are available for download from our model download page:
https://opennlp.apache.org/models.html
The models are compatible with Apache OpenNLP &lt;OPENNLP_VERSION&gt;.
More information about this release can be found in the README.txt at:
https://dist.apache.org/repos/dist/dev/opennlp/&lt;MODEL_TYPE&gt;-&lt;MODEL_VERSION&gt;/README.txt
Details about this model effectiveness can be found in the following report:
https://dist.apache.org/repos/dist/dev/opennlp/&lt;MODEL_TYPE&gt;-&lt;MODEL_VERSION&gt;/opennlp-training-eval-logs-&lt;MODEL_VERSION&gt;-&lt;OPENNLP_VERSION&gt;.zip
--The Apache OpenNLP Team</pre>
</div>
</div>
</li>
</ul>
</div>
</div>
<div class="sect3">
<h4 id="commit_website_changes">Commit Website Changes.</h4>
<div class="ulist">
<ul>
<li>
<p>Commit the website changes.</p>
</li>
<li>
<p>Rebuild opennlp-site and wait for site redeploy</p>
</li>
<li>
<p>Test and review the website. Test that all download links are working.</p>
</li>
</ul>
</div>
</div>
</div>
<div class="sect2">
<h3 id="post_release_steps">Post-Release Steps</h3>
<div class="ulist">
<ul>
<li>
<p>Log the new version at <a href="https://reporter.apache.org/addrelease.html?opennlp" class="bare" target="_blank" rel="noopener">https://reporter.apache.org/addrelease.html?opennlp</a>.</p>
</li>
<li>
<p>Announce the new models on the OpenNLP Twitter.</p>
</li>
<li>
<p>Close the present release ticket in <a href="https://issues.apache.org/jira/browse/OPENNLP" target="_blank" rel="noopener">JIRA</a>.</p>
</li>
<li>
<p>Send announcement email to <a href="mailto:announce@apache.org">announce@apache.org</a>, <a href="mailto:dev@opennlp.apache.org">dev@opennlp.apache.org</a>, <a href="mailto:users@opennlp.apache.org">users@opennlp.apache.org</a>.
This needs to be done from your @apache.org email address or the email will bounce from the announce list.</p>
<div class="listingblock">
<div class="content">
<pre>Title: [ANNOUNCE] OpenNLP Models &lt;version&gt; released
TO: announce@apache.org, users@opennlp.apache.org, dev@opennlp.apache.org</pre>
</div>
</div>
<div class="paragraph">
<p>Message body:</p>
</div>
<div class="listingblock">
<div class="content">
<pre>The Apache OpenNLP library is a machine learning based toolkit for the processing of natural language text.
The Apache OpenNLP team is pleased to announce the release of &lt;MODEL_TYPE&gt;-&lt;MODEL_VERSION&gt; for Apache OpenNLP &lt;OPENNLP_VERSION&gt;.
The models can &lt;ADD_SUMMARY_HERE&gt;
Apache OpenNLP model and reports are available for download from our model download page:
https://opennlp.apache.org/models.html
The models are compatible with Apache OpenNLP &lt;OPENNLP_VERSION&gt;.
More information about this release can be found in the README.txt at:
https://dist.apache.org/repos/dist/dev/opennlp/&lt;MODEL_TYPE&gt;-&lt;MODEL_VERSION&gt;/README.txt
Details about this model effectiveness can be found in the following report:
https://dist.apache.org/repos/dist/dev/opennlp/&lt;MODEL_TYPE&gt;-&lt;MODEL_VERSION&gt;/opennlp-training-eval-logs-&lt;MODEL_VERSION&gt;-&lt;OPENNLP_VERSION&gt;.zip
--The Apache OpenNLP Team</pre>
</div>
</div>
</li>
</ul>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="after_an_unsuccessful_vote">After an Unsuccessful Vote</h2>
<div class="sectionbody">
<div class="paragraph">
<p>The model release vote may fail due to an issue discovered in the release candidate. If the vote fails the model release candidate should be canceled by:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>Sending an email to <a href="mailto:dev@opennlp.apache.org">dev@opennlp.apache.org</a> on the VOTE thread notifying of the vote&#8217;s cancellation.</p>
</li>
<li>
<p>Dropping the dist/dev model area in SVN</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>A new model release candidate can now be prepared. When complete, a new VOTE thread can be started as described in the steps above.</p>
</div>
</div>
</div>
</div>
<footer class='footer'>
<div class="container">
<p class="text-muted">Copyright &copy; 2024 The Apache Software Foundation, Licensed under the
<a href="https://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a> <br>
Apache OpenNLP, OpenNLP, Apache, the Apache feather logo, and the Apache OpenNLP project logo are
trademarks of The Apache Software Foundation. -
<a href="/privacy-policy.html">Privacy Policy</a></p>
</div>
</footer>
<!-- Le javascript
================================================== -->
<!-- Placed at the end of the document so the pages load faster -->
<script src="https://www.apachecon.com/event-images/snippet.js"></script>
<script src="/js/jquery-3.2.1.min.js"></script>
<script src="/js/bootstrap.min.js"></script>
<script src="/js/prettify.js"></script>
<script type="text/javascript">
var link = $('a[href="' + this.location.pathname + '"]');
if (link != undefined)
link.parents('li,ul').addClass('active');
</script>
<!-- Matomo -->
<script>
var _paq = window._paq = window._paq || [];
/* tracker methods like "setCustomDimension" should be called before "trackPageView" */
/* We explicitly disable cookie tracking to avoid privacy issues */
_paq.push(['disableCookies']);
_paq.push(['trackPageView']);
_paq.push(['enableLinkTracking']);
(function() {
var u="//analytics.apache.org/";
_paq.push(['setTrackerUrl', u+'matomo.php']);
_paq.push(['setSiteId', '33']);
var d=document, g=d.createElement('script'), s=d.getElementsByTagName('script')[0];
g.async=true; g.src=u+'matomo.js'; s.parentNode.insertBefore(g,s);
})();
</script>
<!-- End Matomo Code -->
</body>
</html>