publish/documentation/latest/release-guide/index.html - mesos-site - Git at Google

 <!DOCTYPE html>
 <html>
   <head>
     <meta charset="utf-8">
     <title>Apache Mesos - Release Guide</title>
     <meta name="viewport" content="width=device-width, initial-scale=1.0">

     <meta property="og:locale" content="en_US"/>
     <meta property="og:type" content="website"/>
     <meta property="og:title" content="Apache Mesos"/>
     <meta property="og:site_name" content="Apache Mesos"/>
     <meta property="og:url" content="http://mesos.apache.org/"/>
     <meta property="og:image" content="http://mesos.apache.org/assets/img/mesos_logo_fb_preview.png"/>
     <meta property="og:description"
           content="Apache Mesos abstracts resources away from machines,
                    enabling fault-tolerant and elastic distributed systems
                    to easily be built and run effectively."/>

     <meta name="twitter:card" content="summary"/>
     <meta name="twitter:site" content="@ApacheMesos"/>
     <meta name="twitter:title" content="Apache Mesos"/>
     <meta name="twitter:image" content="http://mesos.apache.org/assets/img/mesos_logo_fb_preview.png"/>
     <meta name="twitter:description"
           content="Apache Mesos abstracts resources away from machines,
                    enabling fault-tolerant and elastic distributed systems
                    to easily be built and run effectively."/>

     <link href="//netdna.bootstrapcdn.com/bootstrap/3.1.1/css/bootstrap.min.css" rel="stylesheet">
     <link rel="alternate" type="application/atom+xml" title="Apache Mesos Blog" href="/blog/feed.xml">
     <link href="../../../assets/css/main.css" media="screen" rel="stylesheet" type="text/css" />


     <!-- Google Analytics Magic -->
     <script type="text/javascript">
     var _gaq = _gaq || [];
     _gaq.push(['_setAccount', 'UA-20226872-1']);
     _gaq.push(['_setDomainName', 'apache.org']);
     _gaq.push(['_trackPageview']);

     (function() {
       var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
       ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
       var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
     })();
     </script>

   </head>
   <body>
     <!-- magical breadcrumbs -->
     <div class="topnav">
       <div class="container">
         <ul class="breadcrumb">
           <li>
             <div class="dropdown">
               <a data-toggle="dropdown" href="#">Apache Software Foundation <span class="caret"></span></a>
               <ul class="dropdown-menu" role="menu" aria-labelledby="dLabel">
                 <li><a href="http://www.apache.org">Apache Homepage</a></li>
                 <li><a href="http://www.apache.org/licenses/">License</a></li>
                 <li><a href="http://www.apache.org/foundation/sponsorship.html">Sponsorship</a></li>
                 <li><a href="http://www.apache.org/foundation/thanks.html">Thanks</a></li>
                 <li><a href="http://www.apache.org/security/">Security</a></li>
               </ul>
             </div>
           </li>

           <li><a href="http://mesos.apache.org">Apache Mesos</a></li>


           <li><a href="/documentation
 /">Documentation
 </a></li>


         </ul><!-- /.breadcrumb -->
       </div><!-- /.container -->
     </div><!-- /.topnav -->

     <!-- navbar excitement -->
 <div class="navbar navbar-default navbar-static-top" role="navigation">
   <div class="container">
     <div class="navbar-header">
       <button type="button" class="navbar-toggle collapsed" data-toggle="collapse" data-target="#mesos-menu" 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 src="/assets/img/mesos_logo.png" alt="Apache Mesos logo"/></a>
     </div><!-- /.navbar-header -->

     <div class="navbar-collapse collapse" id="mesos-menu">
       <ul class="nav navbar-nav navbar-right">
         <li><a href="/gettingstarted/">Getting Started</a></li>
         <li><a href="/blog/">Blog</a></li>
         <li><a href="/documentation/latest/">Documentation</a></li>
         <li><a href="/downloads/">Downloads</a></li>
         <li><a href="/community/">Community</a></li>
       </ul>
     </div><!-- /#mesos-menu -->
   </div><!-- /.container -->
 </div><!-- /.navbar -->

 <div class="content">
   <div class="container">
     <div class="row-fluid">
   <div class="col-md-4">
     <h4>If you're new to Mesos</h4>
     <p>See the <a href="/gettingstarted/">getting started</a> page for more
        information about downloading, building, and deploying Mesos.</p>

     <h4>If you'd like to get involved or you're looking for support</h4>
     <p>See our <a href="/community/">community</a> page for more details.</p>
   </div>
   <div class="col-md-8">
     <h1>Release Guide</h1>

 <p>This guide describes the process of doing an official release of Mesos.</p>

 <h2>Prerequisites</h2>

 <ol>
 <li><p>Ensure that you have a GPG key or generate a new one, e.g., using <code>gpg --gen-key</code>.</p></li>
 <li><p>Add your GPG public key to the Apache Mesos dist repository in the KEYS file.</p>

 <ul>
 <li><p>Fetch the svn repository:<br>
 <code>svn co https://dist.apache.org/repos/dist/release/mesos</code></p></li>
 <li><p>Append your public key using one of methods described in KEYS, e.g.:<br>
 <code>(gpg --list-sigs &lt;your name&gt; &amp;&amp; gpg --armor --export &lt;your name&gt;) &gt;&gt; KEYS</code>.</p></li>
 <li><p>Push the commit:<br>
 <code>svn ci</code></p></li>
 </ul>
 </li>
 <li><p>Submit your GPG public key to a keyserver, e.g.,
 <a href="https://pgp.mit.edu">MIT PGP Public Key Server</a>.</p></li>
 <li><p>Add your GPG fingerprint (<code>gpg --fingerprint &lt;your name&gt;</code>) to your
 <a href="https://id.apache.org/">Apache account</a>.</p></li>
 <li><p>Create a Maven settings file (<code>~/.m2/settings.xml</code>) for the Apache
 servers where you must copy your encrypted Apache password which
 you can get from running <code>mvn --encrypt-password</code>.</p>

 <p><strong>NOTE:</strong> You may need to first generate a
 <a href="http://maven.apache.org/guides/mini/guide-encryption.html">master password</a>.</p>

 <pre><code> &lt;settings&gt;
    &lt;servers&gt;
      &lt;server&gt;
        &lt;id&gt;apache.snapshots.https&lt;/id&gt;
        &lt;username&gt;APACHE USERNAME&lt;/username&gt;
        &lt;password&gt;APACHE ENCRYPTED PASSWORD&lt;/password&gt;
      &lt;/server&gt;
      &lt;server&gt;
        &lt;id&gt;apache.releases.https&lt;/id&gt;
        &lt;username&gt;APACHE USERNAME&lt;/username&gt;
        &lt;password&gt;APACHE ENCRYPTED PASSWORD&lt;/password&gt;
      &lt;/server&gt;
    &lt;/servers&gt;
  &lt;/settings&gt;
 </code></pre></li>
 <li><p>Use <code>gpg-agent</code> to avoid typing your passphrase repeatedly.</p></li>
 </ol>


 <h2>Preparation</h2>

 <ol>
 <li><p>Go to <a href="https://issues.apache.org/jira/browse/MESOS">Apache JIRA</a> and make
 sure that the <code>CHANGELOG</code> for the release version is up to date.</p>

 <p><strong>NOTE:</strong> You should move all <strong>Unresolved</strong> tickets marked with <code>Fix Version</code>
 or <code>Target Version</code> as the release version to the next release version.</p>

 <p><strong>PROTIP:</strong> Use a JIRA dashboard
 <a href="https://issues.apache.org/jira/secure/Dashboard.jspa?selectPageId=12329720">(example)</a>
 to track the progress of targeted issues as the release date approaches. This
 JIRA filter may be useful (<code>&lt;X.Y.Z&gt;</code> is the release version):
 <code>project = MESOS AND "Target Version/s" = &lt;X.Y.Z&gt; AND (fixVersion != &lt;X.Y.Z&gt; OR fixVersion = EMPTY)</code></p>

 <p><strong>PROTIP:</strong> Use <code>bulk edit</code> option in JIRA to move the tickets and make sure
 to <strong>uncheck</strong> the option that emails everyone about the move to avoid
 spamming.</p></li>
 <li><p>Checkout the correct branch for the release. For regular releases this is the
 &ldquo;master&rdquo; branch. For patch releases this would be the corresponding release
 branch (e.g., 1.0.x).</p></li>
 <li><p>Update and commit the <code>CHANGELOG</code> for the release.</p>

 <p>For regular releases:</p>

 <ul>
 <li><p>Make sure all new API changes, deprecations, major features, and features
 graduating from experimental to stable are called out at the top of the
 <code>CHANGELOG</code>. This JIRA query may be helpful in identifying some of these
 (<code>&lt;X.Y.Z&gt;</code> is the release version):
 <code>project = MESOS AND "Target Version/s" = &lt;X.Y.Z&gt; AND type = Epic</code></p></li>
 <li><p>Ensure that the &ldquo;Unresolved Critical Issues&rdquo; section is populated
 correctly. This JIRA query may be helpful:
 <code>project = Mesos AND type = bug AND status != Resolved AND priority IN (blocker, critical)</code></p></li>
 <li><p>Prepare a full list of experimental features. The easiest way to do this
 is to take the list from the previous minor release, remove features that
 have been declared stable, and those, that declared experimental in the
 current release. Do not forget to mention features transitioning from
 experimental to stable in this release at the top of the <code>CHANGELOG</code>.</p></li>
 </ul>


 <p><strong>NOTE:</strong> You should use JIRA to generate the major portion of the
 <code>CHANGELOG</code> for you. Click on the release version in
 <a href="https://issues.apache.org/jira/browse/MESOS#selectedTab=com.atlassian.jira.plugin.system.project%3Aversions-panel">JIRA</a>
 and click on the <code>Release Notes</code>. Make sure to configure the release notes
 in text format.</p>

 <p><strong>NOTE:</strong> The JIRA Release Notes will list only tickets with <code>Fix Version</code>
 set to that version. You should check for any Resolved tickets that have
 <code>Target Version</code> set but not <code>Fix Version</code>. Also check for any Unresolved
 or <code>Duplicate</code>/<code>Invalid</code> tickets that incorrectly set the <code>Fix Version</code>.</p>

 <p>For patch releases update the <code>CHANGELOG</code> on master branch and then cherry
 pick onto the release branch.</p></li>
 <li><p>Ensure version in <code>configure.ac</code> and <code>CMakeLists.txt</code> is correctly set for
 the release.</p></li>
 <li><p>Run <code>make &amp;&amp; support/generate-endpoint-help.py</code> and commit any resulting
 changes.</p></li>
 <li><p>Update and commit <code>docs/configuration.md</code> to reflect the current state of
 the master, agent, and configure flags. If this is a patch release, update
 it on master branch and then cherry pick onto the release branch.</p></li>
 <li><p>If this is a regular release, update and commit <code>docs/upgrades.md</code> with
 instructions about how to upgrade a live cluster from the previous release
 version to this release version.</p></li>
 <li><p>If this is a regular release, please ensure that user documentation has been
 added for any new features.</p></li>
 <li><p>Make sure that for any updates of the API, specifically the scheduler API,
 the public mesos protobuf definitions are part of both, <code>include/mesos</code> as
 well as <code>include/mesos/v1</code>.</p>

 <p><strong>NOTE:</strong> This might actually demand code updates if any omissions were
 identified.</p></li>
 </ol>


 <h2>Tagging the Release Candidate</h2>

 <ol>
 <li><p>Ensure that you can build and pass all the tests.</p>

 <pre><code> $ sudo make -j&lt;cores&gt; distcheck
 </code></pre></li>
 <li><p>Run the benchmarks and compare with the previous release for any performance
 regressions:</p>

 <pre><code> $ make bench -j&lt;cores&gt; GTEST_FILTER="*BENCHMARK*"
 </code></pre></li>
 <li><p>First tag the required SHA locally.</p>

 <pre><code> $ git tag &lt;X.Y.Z-rcR&gt;
 </code></pre>

 <p><strong>NOTE:</strong> <code>X.Y.Z</code> is based on <a href="http://semver.org/">semantic versioning</a>
 scheme. <code>R</code> is release candidate version that starts with 1.</p></li>
 <li><p>Tag the release externally and deploy the corresponding JAR to the
 <a href="https://repository.apache.org">Apache maven repository</a>. It is recommended
 to use the <code>support/tag.sh</code> script to accomplish this.</p>

 <pre><code> $ ./support/tag.sh X.Y.Z R
 </code></pre>

 <p><strong>NOTE:</strong> This script assumes that you have the requisite permissions to
 deploy the JAR. For instructions on how to set it up, please refer to
 <code>src/java/MESOS-MAVEN-README</code>.</p>

 <p><strong>NOTE:</strong> gnu-sed (Linux) requires <code>-i''</code> instead of the <code>-i ''</code>
 (space-separated) that default OSX uses. You may need to modify your local
 copy of <code>tag.sh</code> for it to complete successfully.</p></li>
 <li><p>If this is a regular release, create a new release branch (<major>.<minor>.x)
 from this tag.</p>

 <pre><code> $ git checkout -b X.Y.x
 </code></pre>

 <p>Now, update master branch to the <em>next</em>  minor version in <code>configure.ac</code>:
 change <code>AC_INIT([mesos], [X.Y.Z]))</code>, as well as in <code>CMakeLists.txt</code>:
 change <code>set(MESOS_MAJOR_VERSION X)</code>, <code>set(MESOS_MINOR_VERSION Y)</code>,
 <code>set(MESOS_PATCH_VERSION Z)</code> and then commit.</p></li>
 </ol>


 <h2>Voting the Release Candidate</h2>

 <ol>
 <li><p>Once a release candidate is deemed worthy to be officially released you
 should call a vote on the <code>dev@mesos.apache.org</code> (and optionally
 <code>user@mesos.apache.org</code>) mailing list.</p></li>
 <li><p>It is recommended to use the <code>support/vote.sh</code> script to vote the release
 candidate.</p>

 <pre><code> $ ./support/vote.sh X.Y.Z R
 </code></pre></li>
 <li><p>The release script also spits out an email template that you could use to
 send the vote email.</p>

 <p><strong>NOTE:</strong> The <code>date -v+3d</code> command does not work on some platforms (e.g.
 Ubuntu), so you may need to fill in the vote end date manually. The vote
 should last for 3 business days instead of 3 calendar days anyway. Sometimes
 we allow a longer vote, to allow more time for integration testing.</p></li>
 </ol>


 <h2>Preparing a New Release Candidate</h2>

 <ol>
 <li><p>If the vote does not pass (any -1s or showstopper bugs), track the issues
 as new JIRAs for the release.</p></li>
 <li><p>When all known issues are resolved, update the <code>CHANGELOG</code> with the newly
 fixed JIRAs.</p></li>
 <li><p>Once all patches are committed to master, cherry-pick them on to the
 corresponding release branch. This is the same process used for patch
 releases (e.g., 1.0.2) as well.</p>

 <pre><code> $ git checkout X.Y.x
  $ git cherry-pick abcdefgh...
 </code></pre></li>
 <li><p>Now go back up to the &ldquo;Tagging the Release Candidate&rdquo; section and repeat.</p></li>
 </ol>


 <h2>Releasing the Release Candidate</h2>

 <ol>
 <li><p>You should only release an official version if the vote passes with at
 least <strong>3 +1 binding votes and no -1 votes</strong>. For more information, please
 refer to <a href="http://www.apache.org/dev/release.html">Apache release guidelines</a>.</p></li>
 <li><p>It is recommended to use <code>support/release.sh</code> script to release the candidate.</p>

 <pre><code> $ ./support/release.sh X.Y.Z R
 </code></pre></li>
 <li><p>The release script also spits out an email template that you could use to
 notify the mailing lists about the result of the vote and the release.</p>

 <p><strong>NOTE:</strong> Make sure you fill the email template with the names of binding
 and non-binding voters.</p></li>
 <li><p>Update the version in <code>configure.ac</code> and <code>CMakeLists.txt</code> in the <strong>release</strong>
 branch to the <strong>next</strong> patch version.</p></li>
 </ol>


 <h2>Updating the Website</h2>

 <ol>
 <li><p>After a successful release, add the information associated with the release
 in <code>site/data/releases.yml</code>. It is used to generate the release information
 on the website.</p></li>
 <li><p>Update the <a href="/documentation/latest/./getting-started/">Getting Started</a> guide to use the latest
 release link.</p></li>
 <li><p>Check out the website from svn.</p>

 <pre><code> $ svn co https://svn.apache.org/repos/asf/mesos/site mesos-site
 </code></pre>

 <p>See our <a href="https://github.com/apache/mesos/blob/master/site/README.md/">website README</a>
 for details on how to build the website. See the general
 <a href="https://www.apache.org/dev/project-site.html">Apache project website guide</a>
 for details on how to publish the website.</p></li>
 <li><p>Write a blog post announcing the new release and its features and major bug
 fixes. Include a link to the updated website.</p></li>
 </ol>


 <h2>Removing Old Releases from svn</h2>

 <p>Per the guidelines <a href="http://www.apache.org/dev/release.html#when-to-archive">when to archive</a>,
 we should only keep the latest release in each version under development.</p>

 <ol>
 <li><p>Checkout the mesos distribution folder:</p>

 <pre><code> $ svn co https://dist.apache.org/repos/dist/release/mesos
 </code></pre></li>
 <li><p>Remove all minor versions that are no longer under development and commit
 the change.</p></li>
 </ol>


 <h2>Releasing the Version on JIRA</h2>

 <p>Find the released Mesos version
 <a href="https://issues.apache.org/jira/plugins/servlet/project-config/MESOS/versions">here</a>,
 and &ldquo;release&rdquo; it with the correct release date by clicking on
 &ldquo;settings&rdquo;&nbsp;&rarr;&nbsp;&ldquo;Release&rdquo;. Also, make sure to add the names of the
 release managers in &ldquo;Description&rdquo; section.</p>

 <h2>Updating External Tooling</h2>

 <p>Upload the mesos.interface package to PyPi.</p>

 <ol>
 <li><p>Create/use a PyPi account with access to the
 <a href="https://pypi.python.org/pypi?name=mesos.interface&amp;:action=submit_form">mesos.interface submit form</a>.
 You may need to ask a current package owner to add you as an owner/maintainer.</p></li>
 <li><p>Setup your <a href="https://docs.python.org/2/distutils/packageindex.html#pypirc"><code>~/.pypirc</code></a>
 with your PyPi username and password.</p></li>
 <li><p>After a successful Mesos <code>make</code> (any architecture), cd to
 <code>build/src/python/interface</code>.</p></li>
 <li><p>Run <code>python setup.py register</code> to register this package.</p></li>
 <li><p>Run <code>python setup.py sdist bdist_egg upload</code> to upload the source
 distribution and egg for this package.</p></li>
 </ol>


 <p>Update the Mesos Homebrew package.</p>

 <ol>
 <li><p>Update the <a href="https://github.com/Homebrew/homebrew-core/blob/master/Formula/mesos.rb">Homebrew formula for Mesos</a>
 and test.</p></li>
 <li><p>Submit a PR to the <a href="https://github.com/Homebrew/homebrew-core">Homebrew repo</a>.</p></li>
 <li><p>Once accepted, verify that <code>brew install mesos</code> works.</p></li>
 </ol>


   </div>
 </div>

   </div><!-- /.container -->
 </div><!-- /.content -->

 <hr>


     <!-- footer -->
     <div class="footer">
       <div class="container">
         <div class="col-md-4 social-blk">
           <span class="social">
             <a href="https://twitter.com/ApacheMesos"
               class="twitter-follow-button"
               data-show-count="false" data-size="large">Follow @ApacheMesos</a>
             <script>!function(d,s,id){var js,fjs=d.getElementsByTagName(s)[0],p=/^http:/.test(d.location)?'http':'https';if(!d.getElementById(id)){js=d.createElement(s);js.id=id;js.src=p+'://platform.twitter.com/widgets.js';fjs.parentNode.insertBefore(js,fjs);}}(document, 'script', 'twitter-wjs');</script>
             <a href="https://twitter.com/intent/tweet?button_hashtag=mesos"
               class="twitter-hashtag-button"
               data-size="large"
               data-related="ApacheMesos">Tweet #mesos</a>
             <script>!function(d,s,id){var js,fjs=d.getElementsByTagName(s)[0],p=/^http:/.test(d.location)?'http':'https';if(!d.getElementById(id)){js=d.createElement(s);js.id=id;js.src=p+'://platform.twitter.com/widgets.js';fjs.parentNode.insertBefore(js,fjs);}}(document, 'script', 'twitter-wjs');</script>
           </span>
         </div>

         <div class="col-md-8 trademark">
           <p>&copy; 2012-2017 <a href="http://apache.org">The Apache Software Foundation</a>.
             Apache Mesos, the Apache feather logo, and the Apache Mesos project logo are trademarks of The Apache Software Foundation.
           <p>
         </div>
       </div><!-- /.container -->
     </div><!-- /.footer -->

     <!-- JS -->
     <script src="//code.jquery.com/jquery-1.11.0.min.js" type="text/javascript"></script>
     <script src="//netdna.bootstrapcdn.com/bootstrap/3.1.1/js/bootstrap.min.js" type="text/javascript"></script>
   </body>
 </html>
	<!DOCTYPE html>
	<html>
	<head>
	<meta charset="utf-8">
	<title>Apache Mesos - Release Guide</title>
	<meta name="viewport" content="width=device-width, initial-scale=1.0">

	<meta property="og:locale" content="en_US"/>
	<meta property="og:type" content="website"/>
	<meta property="og:title" content="Apache Mesos"/>
	<meta property="og:site_name" content="Apache Mesos"/>
	<meta property="og:url" content="http://mesos.apache.org/"/>
	<meta property="og:image" content="http://mesos.apache.org/assets/img/mesos_logo_fb_preview.png"/>
	<meta property="og:description"
	content="Apache Mesos abstracts resources away from machines,
	enabling fault-tolerant and elastic distributed systems
	to easily be built and run effectively."/>

	<meta name="twitter:card" content="summary"/>
	<meta name="twitter:site" content="@ApacheMesos"/>
	<meta name="twitter:title" content="Apache Mesos"/>
	<meta name="twitter:image" content="http://mesos.apache.org/assets/img/mesos_logo_fb_preview.png"/>
	<meta name="twitter:description"
	content="Apache Mesos abstracts resources away from machines,
	enabling fault-tolerant and elastic distributed systems
	to easily be built and run effectively."/>

	<link href="//netdna.bootstrapcdn.com/bootstrap/3.1.1/css/bootstrap.min.css" rel="stylesheet">
	<link rel="alternate" type="application/atom+xml" title="Apache Mesos Blog" href="/blog/feed.xml">
	<link href="../../../assets/css/main.css" media="screen" rel="stylesheet" type="text/css" />



	<!-- Google Analytics Magic -->
	<script type="text/javascript">
	var _gaq = _gaq \|\| [];
	_gaq.push(['_setAccount', 'UA-20226872-1']);
	_gaq.push(['_setDomainName', 'apache.org']);
	_gaq.push(['_trackPageview']);

	(function() {
	var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
	ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
	var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
	})();
	</script>

	</head>
	<body>
	<!-- magical breadcrumbs -->
	<div class="topnav">
	<div class="container">
	<ul class="breadcrumb">
	<li>
	<div class="dropdown">
	<a data-toggle="dropdown" href="#">Apache Software Foundation <span class="caret"></span></a>
	<ul class="dropdown-menu" role="menu" aria-labelledby="dLabel">
	<li><a href="http://www.apache.org">Apache Homepage</a></li>
	<li><a href="http://www.apache.org/licenses/">License</a></li>
	<li><a href="http://www.apache.org/foundation/sponsorship.html">Sponsorship</a></li>
	<li><a href="http://www.apache.org/foundation/thanks.html">Thanks</a></li>
	<li><a href="http://www.apache.org/security/">Security</a></li>
	</ul>
	</div>
	</li>

	<li><a href="http://mesos.apache.org">Apache Mesos</a></li>


	<li><a href="/documentation
	/">Documentation
	</a></li>


	</ul><!-- /.breadcrumb -->
	</div><!-- /.container -->
	</div><!-- /.topnav -->

	<!-- navbar excitement -->
	<div class="navbar navbar-default navbar-static-top" role="navigation">
	<div class="container">
	<div class="navbar-header">
	<button type="button" class="navbar-toggle collapsed" data-toggle="collapse" data-target="#mesos-menu" 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 src="/assets/img/mesos_logo.png" alt="Apache Mesos logo"/></a>
	</div><!-- /.navbar-header -->

	<div class="navbar-collapse collapse" id="mesos-menu">
	<ul class="nav navbar-nav navbar-right">
	<li><a href="/gettingstarted/">Getting Started</a></li>
	<li><a href="/blog/">Blog</a></li>
	<li><a href="/documentation/latest/">Documentation</a></li>
	<li><a href="/downloads/">Downloads</a></li>
	<li><a href="/community/">Community</a></li>
	</ul>
	</div><!-- /#mesos-menu -->
	</div><!-- /.container -->
	</div><!-- /.navbar -->

	<div class="content">
	<div class="container">
	<div class="row-fluid">
	<div class="col-md-4">
	<h4>If you're new to Mesos</h4>
	<p>See the <a href="/gettingstarted/">getting started</a> page for more
	information about downloading, building, and deploying Mesos.</p>

	<h4>If you'd like to get involved or you're looking for support</h4>
	<p>See our <a href="/community/">community</a> page for more details.</p>
	</div>
	<div class="col-md-8">
	<h1>Release Guide</h1>

	<p>This guide describes the process of doing an official release of Mesos.</p>

	<h2>Prerequisites</h2>

	<ol>
	<li><p>Ensure that you have a GPG key or generate a new one, e.g., using <code>gpg --gen-key</code>.</p></li>
	<li><p>Add your GPG public key to the Apache Mesos dist repository in the KEYS file.</p>

	<ul>
	<li><p>Fetch the svn repository:<br>
	<code>svn co https://dist.apache.org/repos/dist/release/mesos</code></p></li>
	<li><p>Append your public key using one of methods described in KEYS, e.g.:<br>
	<code>(gpg --list-sigs <your name> && gpg --armor --export <your name>) >> KEYS</code>.</p></li>
	<li><p>Push the commit:<br>
	<code>svn ci</code></p></li>
	</ul>
	</li>
	<li><p>Submit your GPG public key to a keyserver, e.g.,
	<a href="https://pgp.mit.edu">MIT PGP Public Key Server</a>.</p></li>
	<li><p>Add your GPG fingerprint (<code>gpg --fingerprint <your name></code>) to your
	<a href="https://id.apache.org/">Apache account</a>.</p></li>
	<li><p>Create a Maven settings file (<code>~/.m2/settings.xml</code>) for the Apache
	servers where you must copy your encrypted Apache password which
	you can get from running <code>mvn --encrypt-password</code>.</p>

	<p><strong>NOTE:</strong> You may need to first generate a
	<a href="http://maven.apache.org/guides/mini/guide-encryption.html">master password</a>.</p>

	<pre><code> <settings>
	<servers>
	<server>
	<id>apache.snapshots.https</id>
	<username>APACHE USERNAME</username>
	<password>APACHE ENCRYPTED PASSWORD</password>
	</server>
	<server>
	<id>apache.releases.https</id>
	<username>APACHE USERNAME</username>
	<password>APACHE ENCRYPTED PASSWORD</password>
	</server>
	</servers>
	</settings>
	</code></pre></li>
	<li><p>Use <code>gpg-agent</code> to avoid typing your passphrase repeatedly.</p></li>
	</ol>


	<h2>Preparation</h2>

	<ol>
	<li><p>Go to <a href="https://issues.apache.org/jira/browse/MESOS">Apache JIRA</a> and make
	sure that the <code>CHANGELOG</code> for the release version is up to date.</p>

	<p><strong>NOTE:</strong> You should move all <strong>Unresolved</strong> tickets marked with <code>Fix Version</code>
	or <code>Target Version</code> as the release version to the next release version.</p>

	<p><strong>PROTIP:</strong> Use a JIRA dashboard
	<a href="https://issues.apache.org/jira/secure/Dashboard.jspa?selectPageId=12329720">(example)</a>
	to track the progress of targeted issues as the release date approaches. This
	JIRA filter may be useful (<code><X.Y.Z></code> is the release version):
	<code>project = MESOS AND "Target Version/s" = <X.Y.Z> AND (fixVersion != <X.Y.Z> OR fixVersion = EMPTY)</code></p>

	<p><strong>PROTIP:</strong> Use <code>bulk edit</code> option in JIRA to move the tickets and make sure
	to <strong>uncheck</strong> the option that emails everyone about the move to avoid
	spamming.</p></li>
	<li><p>Checkout the correct branch for the release. For regular releases this is the
	“master” branch. For patch releases this would be the corresponding release
	branch (e.g., 1.0.x).</p></li>
	<li><p>Update and commit the <code>CHANGELOG</code> for the release.</p>

	<p>For regular releases:</p>

	<ul>
	<li><p>Make sure all new API changes, deprecations, major features, and features
	graduating from experimental to stable are called out at the top of the
	<code>CHANGELOG</code>. This JIRA query may be helpful in identifying some of these
	(<code><X.Y.Z></code> is the release version):
	<code>project = MESOS AND "Target Version/s" = <X.Y.Z> AND type = Epic</code></p></li>
	<li><p>Ensure that the “Unresolved Critical Issues” section is populated
	correctly. This JIRA query may be helpful:
	<code>project = Mesos AND type = bug AND status != Resolved AND priority IN (blocker, critical)</code></p></li>
	<li><p>Prepare a full list of experimental features. The easiest way to do this
	is to take the list from the previous minor release, remove features that
	have been declared stable, and those, that declared experimental in the
	current release. Do not forget to mention features transitioning from
	experimental to stable in this release at the top of the <code>CHANGELOG</code>.</p></li>
	</ul>


	<p><strong>NOTE:</strong> You should use JIRA to generate the major portion of the
	<code>CHANGELOG</code> for you. Click on the release version in
	<a href="https://issues.apache.org/jira/browse/MESOS#selectedTab=com.atlassian.jira.plugin.system.project%3Aversions-panel">JIRA</a>
	and click on the <code>Release Notes</code>. Make sure to configure the release notes
	in text format.</p>

	<p><strong>NOTE:</strong> The JIRA Release Notes will list only tickets with <code>Fix Version</code>
	set to that version. You should check for any Resolved tickets that have
	<code>Target Version</code> set but not <code>Fix Version</code>. Also check for any Unresolved
	or <code>Duplicate</code>/<code>Invalid</code> tickets that incorrectly set the <code>Fix Version</code>.</p>

	<p>For patch releases update the <code>CHANGELOG</code> on master branch and then cherry
	pick onto the release branch.</p></li>
	<li><p>Ensure version in <code>configure.ac</code> and <code>CMakeLists.txt</code> is correctly set for
	the release.</p></li>
	<li><p>Run <code>make && support/generate-endpoint-help.py</code> and commit any resulting
	changes.</p></li>
	<li><p>Update and commit <code>docs/configuration.md</code> to reflect the current state of
	the master, agent, and configure flags. If this is a patch release, update
	it on master branch and then cherry pick onto the release branch.</p></li>
	<li><p>If this is a regular release, update and commit <code>docs/upgrades.md</code> with
	instructions about how to upgrade a live cluster from the previous release
	version to this release version.</p></li>
	<li><p>If this is a regular release, please ensure that user documentation has been
	added for any new features.</p></li>
	<li><p>Make sure that for any updates of the API, specifically the scheduler API,
	the public mesos protobuf definitions are part of both, <code>include/mesos</code> as
	well as <code>include/mesos/v1</code>.</p>

	<p><strong>NOTE:</strong> This might actually demand code updates if any omissions were
	identified.</p></li>
	</ol>


	<h2>Tagging the Release Candidate</h2>

	<ol>
	<li><p>Ensure that you can build and pass all the tests.</p>

	<pre><code> $ sudo make -j<cores> distcheck
	</code></pre></li>
	<li><p>Run the benchmarks and compare with the previous release for any performance
	regressions:</p>

	<pre><code> $ make bench -j<cores> GTEST_FILTER="BENCHMARK"
	</code></pre></li>
	<li><p>First tag the required SHA locally.</p>

	<pre><code> $ git tag <X.Y.Z-rcR>
	</code></pre>

	<p><strong>NOTE:</strong> <code>X.Y.Z</code> is based on <a href="http://semver.org/">semantic versioning</a>
	scheme. <code>R</code> is release candidate version that starts with 1.</p></li>
	<li><p>Tag the release externally and deploy the corresponding JAR to the
	<a href="https://repository.apache.org">Apache maven repository</a>. It is recommended
	to use the <code>support/tag.sh</code> script to accomplish this.</p>

	<pre><code> $ ./support/tag.sh X.Y.Z R
	</code></pre>

	<p><strong>NOTE:</strong> This script assumes that you have the requisite permissions to
	deploy the JAR. For instructions on how to set it up, please refer to
	<code>src/java/MESOS-MAVEN-README</code>.</p>

	<p><strong>NOTE:</strong> gnu-sed (Linux) requires <code>-i''</code> instead of the <code>-i ''</code>
	(space-separated) that default OSX uses. You may need to modify your local
	copy of <code>tag.sh</code> for it to complete successfully.</p></li>
	<li><p>If this is a regular release, create a new release branch (<major>.<minor>.x)
	from this tag.</p>

	<pre><code> $ git checkout -b X.Y.x
	</code></pre>

	<p>Now, update master branch to the <em>next</em> minor version in <code>configure.ac</code>:
	change <code>AC_INIT([mesos], [X.Y.Z]))</code>, as well as in <code>CMakeLists.txt</code>:
	change <code>set(MESOS_MAJOR_VERSION X)</code>, <code>set(MESOS_MINOR_VERSION Y)</code>,
	<code>set(MESOS_PATCH_VERSION Z)</code> and then commit.</p></li>
	</ol>


	<h2>Voting the Release Candidate</h2>

	<ol>
	<li><p>Once a release candidate is deemed worthy to be officially released you
	should call a vote on the <code>dev@mesos.apache.org</code> (and optionally
	<code>user@mesos.apache.org</code>) mailing list.</p></li>
	<li><p>It is recommended to use the <code>support/vote.sh</code> script to vote the release
	candidate.</p>

	<pre><code> $ ./support/vote.sh X.Y.Z R
	</code></pre></li>
	<li><p>The release script also spits out an email template that you could use to
	send the vote email.</p>

	<p><strong>NOTE:</strong> The <code>date -v+3d</code> command does not work on some platforms (e.g.
	Ubuntu), so you may need to fill in the vote end date manually. The vote
	should last for 3 business days instead of 3 calendar days anyway. Sometimes
	we allow a longer vote, to allow more time for integration testing.</p></li>
	</ol>


	<h2>Preparing a New Release Candidate</h2>

	<ol>
	<li><p>If the vote does not pass (any -1s or showstopper bugs), track the issues
	as new JIRAs for the release.</p></li>
	<li><p>When all known issues are resolved, update the <code>CHANGELOG</code> with the newly
	fixed JIRAs.</p></li>
	<li><p>Once all patches are committed to master, cherry-pick them on to the
	corresponding release branch. This is the same process used for patch
	releases (e.g., 1.0.2) as well.</p>

	<pre><code> $ git checkout X.Y.x
	$ git cherry-pick abcdefgh...
	</code></pre></li>
	<li><p>Now go back up to the “Tagging the Release Candidate” section and repeat.</p></li>
	</ol>


	<h2>Releasing the Release Candidate</h2>

	<ol>
	<li><p>You should only release an official version if the vote passes with at
	least <strong>3 +1 binding votes and no -1 votes</strong>. For more information, please
	refer to <a href="http://www.apache.org/dev/release.html">Apache release guidelines</a>.</p></li>
	<li><p>It is recommended to use <code>support/release.sh</code> script to release the candidate.</p>

	<pre><code> $ ./support/release.sh X.Y.Z R
	</code></pre></li>
	<li><p>The release script also spits out an email template that you could use to
	notify the mailing lists about the result of the vote and the release.</p>

	<p><strong>NOTE:</strong> Make sure you fill the email template with the names of binding
	and non-binding voters.</p></li>
	<li><p>Update the version in <code>configure.ac</code> and <code>CMakeLists.txt</code> in the <strong>release</strong>
	branch to the <strong>next</strong> patch version.</p></li>
	</ol>


	<h2>Updating the Website</h2>

	<ol>
	<li><p>After a successful release, add the information associated with the release
	in <code>site/data/releases.yml</code>. It is used to generate the release information
	on the website.</p></li>
	<li><p>Update the <a href="/documentation/latest/./getting-started/">Getting Started</a> guide to use the latest
	release link.</p></li>
	<li><p>Check out the website from svn.</p>

	<pre><code> $ svn co https://svn.apache.org/repos/asf/mesos/site mesos-site
	</code></pre>

	<p>See our <a href="https://github.com/apache/mesos/blob/master/site/README.md/">website README</a>
	for details on how to build the website. See the general
	<a href="https://www.apache.org/dev/project-site.html">Apache project website guide</a>
	for details on how to publish the website.</p></li>
	<li><p>Write a blog post announcing the new release and its features and major bug
	fixes. Include a link to the updated website.</p></li>
	</ol>


	<h2>Removing Old Releases from svn</h2>

	<p>Per the guidelines <a href="http://www.apache.org/dev/release.html#when-to-archive">when to archive</a>,
	we should only keep the latest release in each version under development.</p>

	<ol>
	<li><p>Checkout the mesos distribution folder:</p>

	<pre><code> $ svn co https://dist.apache.org/repos/dist/release/mesos
	</code></pre></li>
	<li><p>Remove all minor versions that are no longer under development and commit
	the change.</p></li>
	</ol>


	<h2>Releasing the Version on JIRA</h2>

	<p>Find the released Mesos version
	<a href="https://issues.apache.org/jira/plugins/servlet/project-config/MESOS/versions">here</a>,
	and “release” it with the correct release date by clicking on
	“settings” → “Release”. Also, make sure to add the names of the
	release managers in “Description” section.</p>

	<h2>Updating External Tooling</h2>

	<p>Upload the mesos.interface package to PyPi.</p>

	<ol>
	<li><p>Create/use a PyPi account with access to the
	<a href="https://pypi.python.org/pypi?name=mesos.interface&:action=submit_form">mesos.interface submit form</a>.
	You may need to ask a current package owner to add you as an owner/maintainer.</p></li>
	<li><p>Setup your <a href="https://docs.python.org/2/distutils/packageindex.html#pypirc"><code>~/.pypirc</code></a>
	with your PyPi username and password.</p></li>
	<li><p>After a successful Mesos <code>make</code> (any architecture), cd to
	<code>build/src/python/interface</code>.</p></li>
	<li><p>Run <code>python setup.py register</code> to register this package.</p></li>
	<li><p>Run <code>python setup.py sdist bdist_egg upload</code> to upload the source
	distribution and egg for this package.</p></li>
	</ol>


	<p>Update the Mesos Homebrew package.</p>

	<ol>
	<li><p>Update the <a href="https://github.com/Homebrew/homebrew-core/blob/master/Formula/mesos.rb">Homebrew formula for Mesos</a>
	and test.</p></li>
	<li><p>Submit a PR to the <a href="https://github.com/Homebrew/homebrew-core">Homebrew repo</a>.</p></li>
	<li><p>Once accepted, verify that <code>brew install mesos</code> works.</p></li>
	</ol>


	</div>
	</div>

	</div><!-- /.container -->
	</div><!-- /.content -->

	<hr>



	<!-- footer -->
	<div class="footer">
	<div class="container">
	<div class="col-md-4 social-blk">
	<span class="social">
	<a href="https://twitter.com/ApacheMesos"
	class="twitter-follow-button"
	data-show-count="false" data-size="large">Follow @ApacheMesos</a>
	<script>!function(d,s,id){var js,fjs=d.getElementsByTagName(s)[0],p=/^http:/.test(d.location)?'http':'https';if(!d.getElementById(id)){js=d.createElement(s);js.id=id;js.src=p+'://platform.twitter.com/widgets.js';fjs.parentNode.insertBefore(js,fjs);}}(document, 'script', 'twitter-wjs');</script>
	<a href="https://twitter.com/intent/tweet?button_hashtag=mesos"
	class="twitter-hashtag-button"
	data-size="large"
	data-related="ApacheMesos">Tweet #mesos</a>
	<script>!function(d,s,id){var js,fjs=d.getElementsByTagName(s)[0],p=/^http:/.test(d.location)?'http':'https';if(!d.getElementById(id)){js=d.createElement(s);js.id=id;js.src=p+'://platform.twitter.com/widgets.js';fjs.parentNode.insertBefore(js,fjs);}}(document, 'script', 'twitter-wjs');</script>
	</span>
	</div>

	<div class="col-md-8 trademark">
	<p>© 2012-2017 <a href="http://apache.org">The Apache Software Foundation</a>.
	Apache Mesos, the Apache feather logo, and the Apache Mesos project logo are trademarks of The Apache Software Foundation.
	<p>
	</div>
	</div><!-- /.container -->
	</div><!-- /.footer -->

	<!-- JS -->
	<script src="//code.jquery.com/jquery-1.11.0.min.js" type="text/javascript"></script>
	<script src="//netdna.bootstrapcdn.com/bootstrap/3.1.1/js/bootstrap.min.js" type="text/javascript"></script>
	</body>
	</html>