[llvm-commits] [llvm] r169608 - in /llvm/trunk/docs: HowToReleaseLLVM.html HowToReleaseLLVM.rst development_process.rst
Dmitri Gribenko
gribozavr at gmail.com
Fri Dec 7 08:42:48 PST 2012
Author: gribozavr
Date: Fri Dec 7 10:42:48 2012
New Revision: 169608
URL: http://llvm.org/viewvc/llvm-project?rev=169608&view=rev
Log:
Convert HowToReleaseLLVM.html to reST
Patch by Alexander Zinenko.
Added:
llvm/trunk/docs/HowToReleaseLLVM.rst
Removed:
llvm/trunk/docs/HowToReleaseLLVM.html
Modified:
llvm/trunk/docs/development_process.rst
Removed: llvm/trunk/docs/HowToReleaseLLVM.html
URL: http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/HowToReleaseLLVM.html?rev=169607&view=auto
==============================================================================
--- llvm/trunk/docs/HowToReleaseLLVM.html (original)
+++ llvm/trunk/docs/HowToReleaseLLVM.html (removed)
@@ -1,581 +0,0 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
- "http://www.w3.org/TR/html4/strict.dtd">
-<html>
-<head>
- <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
- <title>How To Release LLVM To The Public</title>
- <link rel="stylesheet" href="_static/llvm.css" type="text/css">
-</head>
-<body>
-
-<h1>How To Release LLVM To The Public</h1>
-<ol>
- <li><a href="#introduction">Introduction</a></li>
- <li><a href="#criteria">Qualification Criteria</a></li>
- <li><a href="#introduction">Release Timeline</a></li>
- <li><a href="#process">Release Process</a></li>
-</ol>
-<div class="doc_author">
- <p>Written by <a href="mailto:tonic at nondot.org">Tanya Lattner</a>,
- <a href="mailto:rspencer at x10sys.com">Reid Spencer</a>,
- <a href="mailto:criswell at cs.uiuc.edu">John Criswell</a>, &
- <a href="mailto:wendling at apple.com">Bill Wendling</a>
- </p>
-</div>
-
-<!-- *********************************************************************** -->
-<h2><a name="introduction">Introduction</a></h2>
-<!-- *********************************************************************** -->
-
-<div>
-
-<p>This document contains information about successfully releasing LLVM —
- including subprojects: e.g., <tt>clang</tt> and <tt>dragonegg</tt> — to
- the public. It is the Release Manager's responsibility to ensure that a high
- quality build of LLVM is released.</p>
-
-</div>
-
-<!-- *********************************************************************** -->
-<h2><a name="process">Release Timeline</a></h2>
-<!-- *********************************************************************** -->
-<div>
-
-<p>LLVM is released on a time based schedule — roughly every 6 months. We
- do not normally have dot releases because of the nature of LLVM's incremental
- development philosophy. That said, the only thing preventing dot releases for
- critical bug fixes from happening is a lack of resources — testers,
- machines, time, etc. And, because of the high quality we desire for LLVM
- releases, we cannot allow for a truncated form of release qualification.</p>
-
-<p>The release process is roughly as follows:</p>
-
-<ul>
- <li><p>Set code freeze and branch creation date for 6 months after last code
- freeze date. Announce release schedule to the LLVM community and update
- the website.</p></li>
-
- <li><p>Create release branch and begin release process.</p></li>
-
- <li><p>Send out release candidate sources for first round of testing. Testing
- lasts 7-10 days. During the first round of testing, any regressions found
- should be fixed. Patches are merged from mainline into the release
- branch. Also, all features need to be completed during this time. Any
- features not completed at the end of the first round of testing will be
- removed or disabled for the release.</p></li>
-
- <li><p>Generate and send out the second release candidate sources. Only
- <em>critial</em> bugs found during this testing phase will be fixed. Any
- bugs introduced by merged patches will be fixed. If so a third round of
- testing is needed.</p></li>
-
- <li><p>The release notes are updated.</p></li>
-
- <li><p>Finally, release!</p></li>
-</ul>
-
-</div>
-
-<!-- *********************************************************************** -->
-<h2><a name="process">Release Process</a></h2>
-<!-- *********************************************************************** -->
-
-<div>
-
-<ol>
- <li><a href="#release-admin">Release Administrative Tasks</a>
- <ol>
- <li><a href="#branch">Create Release Branch</a></li>
- <li><a href="#verchanges">Update Version Numbers</a></li>
- </ol>
- </li>
- <li><a href="#release-build">Building the Release</a>
- <ol>
- <li><a href="#dist">Build the LLVM Source Distributions</a></li>
- <li><a href="#build">Build LLVM</a></li>
- <li><a href="#clangbin">Build the Clang Binary Distribution</a></li>
- <li><a href="#target-build">Target Specific Build Details</a></li>
- </ol>
- </li>
- <li><a href="#release-qualify">Release Qualification Criteria</a>
- <ol>
- <li><a href="#llvm-qualify">Qualify LLVM</a></li>
- <li><a href="#clang-qualify">Qualify Clang</a></li>
- <li><a href="#targets">Specific Target Qualification Details</a></li>
- </ol>
- </li>
-
- <li><a href="#commTest">Community Testing</a></li>
- <li><a href="#release-patch">Release Patch Rules</a></li>
- <li><a href="#release-final">Release final tasks</a>
- <ol>
- <li><a href="#updocs">Update Documentation</a></li>
- <li><a href="#tag">Tag the LLVM Final Release</a></li>
- <li><a href="#updemo">Update the LLVM Demo Page</a></li>
- <li><a href="#webupdates">Update the LLVM Website</a></li>
- <li><a href="#announce">Announce the Release</a></li>
- </ol>
- </li>
-</ol>
-
-<!-- ======================================================================= -->
-<h3><a name="release-admin">Release Administrative Tasks</a></h3>
-
-<div>
-
-<p>This section describes a few administrative tasks that need to be done for
- the release process to begin. Specifically, it involves:</p>
-
-<ul>
- <li>Creating the release branch,</li>
- <li>Setting version numbers, and</li>
- <li>Tagging release candidates for the release team to begin testing</li>
-</ul>
-
-<!-- ======================================================================= -->
-<h4><a name="branch">Create Release Branch</a></h4>
-
-<div>
-
-<p>Branch the Subversion trunk using the following procedure:</p>
-
-<ol>
- <li><p>Remind developers that the release branching is imminent and to refrain
- from committing patches that might break the build. E.g., new features,
- large patches for works in progress, an overhaul of the type system, an
- exciting new TableGen feature, etc.</p></li>
-
- <li><p>Verify that the current Subversion trunk is in decent shape by
- examining nightly tester and buildbot results.</p></li>
-
- <li><p>Create the release branch for <tt>llvm</tt>, <tt>clang</tt>,
- the <tt>test-suite</tt>, and <tt>dragonegg</tt> from the last known good
- revision. The branch's name is <tt>release_<i>XY</i></tt>,
- where <tt>X</tt> is the major and <tt>Y</tt> the minor release
- numbers. The branches should be created using the following commands:</p>
-
-<div class="doc_code">
-<pre>
-$ svn copy https://llvm.org/svn/llvm-project/llvm/trunk \
- https://llvm.org/svn/llvm-project/llvm/branches/release_<i>XY</i>
-
-$ svn copy https://llvm.org/svn/llvm-project/cfe/trunk \
- https://llvm.org/svn/llvm-project/cfe/branches/release_<i>XY</i>
-
-$ svn copy https://llvm.org/svn/llvm-project/dragonegg/trunk \
- https://llvm.org/svn/llvm-project/dragonegg/branches/release_<i>XY</i>
-
-$ svn copy https://llvm.org/svn/llvm-project/test-suite/trunk \
- https://llvm.org/svn/llvm-project/test-suite/branches/release_<i>XY</i>
-</pre>
-</div></li>
-
- <li><p>Advise developers that they may now check their patches into the
- Subversion tree again.</p></li>
-
- <li><p>The Release Manager should switch to the release branch, because all
- changes to the release will now be done in the branch. The easiest way to
- do this is to grab a working copy using the following commands:</p>
-
-<div class="doc_code">
-<pre>
-$ svn co https://llvm.org/svn/llvm-project/llvm/branches/release_<i>XY</i> llvm-<i>X.Y</i>
-
-$ svn co https://llvm.org/svn/llvm-project/cfe/branches/release_<i>XY</i> clang-<i>X.Y</i>
-
-$ svn co https://llvm.org/svn/llvm-project/dragonegg/branches/release_<i>XY</i> dragonegg-<i>X.Y</i>
-
-$ svn co https://llvm.org/svn/llvm-project/test-suite/branches/release_<i>XY</i> test-suite-<i>X.Y</i>
-</pre>
-</div></li>
-</ol>
-
-</div>
-
-<!-- ======================================================================= -->
-<h4><a name="verchanges">Update LLVM Version</a></h4>
-
-<div>
-
-<p>After creating the LLVM release branch, update the release branches'
- <tt>autoconf</tt> and <tt>configure.ac</tt> versions from '<tt>X.Ysvn</tt>'
- to '<tt>X.Y</tt>'. Update it on mainline as well to be the next version
- ('<tt>X.Y+1svn</tt>'). Regenerate the configure scripts for both
- <tt>llvm</tt> and the <tt>test-suite</tt>.</p>
-
-<p>In addition, the version numbers of all the Bugzilla components must be
- updated for the next release.</p>
-
-</div>
-
-<!-- ======================================================================= -->
-<h4><a name="dist">Build the LLVM Release Candidates</a></h4>
-
-<div>
-
-<p>Create release candidates for <tt>llvm</tt>, <tt>clang</tt>,
- <tt>dragonegg</tt>, and the LLVM <tt>test-suite</tt> by tagging the branch
- with the respective release candidate number. For instance, to
- create <b>Release Candidate 1</b> you would issue the following commands:</p>
-
-<div class="doc_code">
-<pre>
-$ svn mkdir https://llvm.org/svn/llvm-project/llvm/tags/RELEASE_<i>XY</i>
-$ svn copy https://llvm.org/svn/llvm-project/llvm/branches/release_<i>XY</i> \
- https://llvm.org/svn/llvm-project/llvm/tags/RELEASE_<i>XY</i>/rc1
-
-$ svn mkdir https://llvm.org/svn/llvm-project/cfe/tags/RELEASE_<i>XY</i>
-$ svn copy https://llvm.org/svn/llvm-project/cfe/branches/release_<i>XY</i> \
- https://llvm.org/svn/llvm-project/cfe/tags/RELEASE_<i>XY</i>/rc1
-
-$ svn mkdir https://llvm.org/svn/llvm-project/dragonegg/tags/RELEASE_<i>XY</i>
-$ svn copy https://llvm.org/svn/llvm-project/dragonegg/branches/release_<i>XY</i> \
- https://llvm.org/svn/llvm-project/dragonegg/tags/RELEASE_<i>XY</i>/rc1
-
-$ svn mkdir https://llvm.org/svn/llvm-project/test-suite/tags/RELEASE_<i>XY</i>
-$ svn copy https://llvm.org/svn/llvm-project/test-suite/branches/release_<i>XY</i> \
- https://llvm.org/svn/llvm-project/test-suite/tags/RELEASE_<i>XY</i>/rc1
-</pre>
-</div>
-
-<p>Similarly, <b>Release Candidate 2</b> would be named <tt>RC2</tt> and so
- on. This keeps a permanent copy of the release candidate around for people to
- export and build as they wish. The final released sources will be tagged in
- the <tt>RELEASE_<i>XY</i></tt> directory as <tt>Final</tt>
- (c.f. <a href="#tag">Tag the LLVM Final Release</a>).</p>
-
-<p>The Release Manager may supply pre-packaged source tarballs for users. This
- can be done with the following commands:</p>
-
-<div class="doc_code">
-<pre>
-$ svn export https://llvm.org/svn/llvm-project/llvm/tags/RELEASE_<i>XY</i>/rc1 llvm-<i>X.Y</i>rc1
-$ svn export https://llvm.org/svn/llvm-project/cfe/tags/RELEASE_<i>XY</i>/rc1 clang-<i>X.Y</i>rc1
-$ svn export https://llvm.org/svn/llvm-project/dragonegg/tags/RELEASE_<i>XY</i>/rc1 dragonegg-<i>X.Y</i>rc1
-$ svn export https://llvm.org/svn/llvm-project/test-suite/tags/RELEASE_<i>XY</i>/rc1 llvm-test-<i>X.Y</i>rc1
-
-$ tar -cvf - llvm-<i>X.Y</i>rc1 | gzip > llvm-<i>X.Y</i>rc1.src.tar.gz
-$ tar -cvf - clang-<i>X.Y</i>rc1 | gzip > clang-<i>X.Y</i>rc1.src.tar.gz
-$ tar -cvf - dragonegg-<i>X.Y</i>rc1 | gzip > dragonegg-<i>X.Y</i>rc1.src.tar.gz
-$ tar -cvf - llvm-test-<i>X.Y</i>rc1 | gzip > llvm-test-<i>X.Y</i>rc1.src.tar.gz
-</pre>
-</div>
-
-</div>
-
-</div>
-
-<!-- ======================================================================= -->
-<h3><a name="release-build">Building the Release</a></h3>
-
-<div>
-
-<p>The builds of <tt>llvm</tt>, <tt>clang</tt>, and <tt>dragonegg</tt>
- <em>must</em> be free of errors and warnings in Debug, Release+Asserts, and
- Release builds. If all builds are clean, then the release passes Build
- Qualification.</p>
-
-<p>The <tt>make</tt> options for building the different modes:</p>
-
-<table>
- <tr><th>Mode</th><th>Options</th></tr>
- <tr align="left"><td>Debug</td><td><tt>ENABLE_OPTIMIZED=0</tt></td></tr>
- <tr align="left"><td>Release+Asserts</td><td><tt>ENABLE_OPTIMIZED=1</tt></td></tr>
- <tr align="left"><td>Release</td><td><tt>ENABLE_OPTIMIZED=1 DISABLE_ASSERTIONS=1</tt></td></tr>
-</table>
-
-<!-- ======================================================================= -->
-<h4><a name="build">Build LLVM</a></h4>
-
-<div>
-
-<p>Build <tt>Debug</tt>, <tt>Release+Asserts</tt>, and <tt>Release</tt> versions
- of <tt>llvm</tt> on all supported platforms. Directions to build
- <tt>llvm</tt> are <a href="GettingStarted.html#quickstart">here</a>.</p>
-
-</div>
-
-<!-- ======================================================================= -->
-<h4><a name="clangbin">Build Clang Binary Distribution</a></h4>
-
-<div>
-
-<p>Creating the <tt>clang</tt> binary distribution
- (Debug/Release+Asserts/Release) requires performing the following steps for
- each supported platform:</p>
-
-<ol>
- <li>Build clang according to the directions
- <a href="http://clang.llvm.org/get_started.html">here</a>.</li>
-
- <li>Build both a Debug and Release version of clang. The binary will be the
- Release build.</lI>
-
- <li>Package <tt>clang</tt> (details to follow).</li>
-</ol>
-
-</div>
-
-<!-- ======================================================================= -->
-<h4><a name="target-build">Target Specific Build Details</a></h4>
-
-<div>
-
-<p>The table below specifies which compilers are used for each Arch/OS
- combination when qualifying the build of <tt>llvm</tt>, <tt>clang</tt>,
- and <tt>dragonegg</tt>.</p>
-
-<table>
- <tr><th>Architecture</th> <th>OS</th> <th>compiler</th></tr>
- <tr><td>x86-32</td> <td>Mac OS 10.5</td> <td>gcc 4.0.1</td></tr>
- <tr><td>x86-32</td> <td>Linux</td> <td>gcc 4.2.X, gcc 4.3.X</td></tr>
- <tr><td>x86-32</td> <td>FreeBSD</td> <td>gcc 4.2.X</td></tr>
- <tr><td>x86-32</td> <td>mingw</td> <td>gcc 3.4.5</td></tr>
- <tr><td>x86-64</td> <td>Mac OS 10.5</td> <td>gcc 4.0.1</td></tr>
- <tr><td>x86-64</td> <td>Linux</td> <td>gcc 4.2.X, gcc 4.3.X</td></tr>
- <tr><td>x86-64</td> <td>FreeBSD</td> <td>gcc 4.2.X</td></tr>
-</table>
-
-</div>
-
-</div>
-
-<!-- ======================================================================= -->
-<h3><a name="release-qualify">Building the Release</a></h3>
-
-<div>
-
-<p>A release is qualified when it has no regressions from the previous release
- (or baseline). Regressions are related to correctness first and performance
- second. (We may tolerate some minor performance regressions if they are
- deemed necessary for the general quality of the compiler.)</p>
-
-<p><b>Regressions are new failures in the set of tests that are used to qualify
- each product and only include things on the list. Every release will have
- some bugs in it. It is the reality of developing a complex piece of
- software. We need a very concrete and definitive release criteria that
- ensures we have monotonically improving quality on some metric. The metric we
- use is described below. This doesn't mean that we don't care about other
- criteria, but these are the criteria which we found to be most important and
- which must be satisfied before a release can go out</b></p>
-
-<!-- ======================================================================= -->
-<h4><a name="llvm-qualify">Qualify LLVM</a></h4>
-
-<div>
-
-<p>LLVM is qualified when it has a clean test run without a front-end. And it
- has no regressions when using either <tt>clang</tt> or <tt>dragonegg</tt>
- with the <tt>test-suite</tt> from the previous release.</p>
-
-</div>
-
-<!-- ======================================================================= -->
-<h4><a name="clang-qualify">Qualify Clang</a></h4>
-
-<div>
-
-<p><tt>Clang</tt> is qualified when front-end specific tests in the
- <tt>llvm</tt> dejagnu test suite all pass, clang's own test suite passes
- cleanly, and there are no regressions in the <tt>test-suite</tt>.</p>
-
-</div>
-
-<!-- ======================================================================= -->
-<h4><a name="targets">Specific Target Qualification Details</a></h4>
-
-<div>
-
-<table>
- <tr><th>Architecture</th> <th>OS</th> <th>clang baseline</th> <th>tests</th></tr>
- <tr><td>x86-32</td> <td>Linux</td> <td>last release</td> <td>llvm dejagnu, clang tests, test-suite (including spec)</td></tr>
- <tr><td>x86-32</td> <td>FreeBSD</td> <td>last release</td> <td>llvm dejagnu, clang tests, test-suite</td></tr>
- <tr><td>x86-32</td> <td>mingw</td> <td>none</td> <td>QT</td></tr>
- <tr><td>x86-64</td> <td>Mac OS 10.X</td> <td>last release</td> <td>llvm dejagnu, clang tests, test-suite (including spec)</td></tr>
- <tr><td>x86-64</td> <td>Linux</td> <td>last release</td> <td>llvm dejagnu, clang tests, test-suite (including spec)</td></tr>
- <tr><td>x86-64</td> <td>FreeBSD</td> <td>last release</td> <td>llvm dejagnu, clang tests, test-suite</td></tr>
-</table>
-
-</div>
-
-</div>
-
-<!-- ======================================================================= -->
-<h3><a name="commTest">Community Testing</a></h3>
-<div>
-
-<p>Once all testing has been completed and appropriate bugs filed, the release
- candidate tarballs are put on the website and the LLVM community is
- notified. Ask that all LLVM developers test the release in 2 ways:</p>
-
-<ol>
- <li>Download <tt>llvm-<i>X.Y</i></tt>, <tt>llvm-test-<i>X.Y</i></tt>, and the
- appropriate <tt>clang</tt> binary. Build LLVM. Run <tt>make check</tt> and
- the full LLVM test suite (<tt>make TEST=nightly report</tt>).</li>
-
- <li>Download <tt>llvm-<i>X.Y</i></tt>, <tt>llvm-test-<i>X.Y</i></tt>, and the
- <tt>clang</tt> sources. Compile everything. Run <tt>make check</tt> and
- the full LLVM test suite (<tt>make TEST=nightly report</tt>).</li>
-</ol>
-
-<p>Ask LLVM developers to submit the test suite report and <tt>make check</tt>
- results to the list. Verify that there are no regressions from the previous
- release. The results are not used to qualify a release, but to spot other
- potential problems. For unsupported targets, verify that <tt>make check</tt>
- is at least clean.</p>
-
-<p>During the first round of testing, all regressions must be fixed before the
- second release candidate is tagged.</p>
-
-<p>If this is the second round of testing, the testing is only to ensure that
- bug fixes previously merged in have not created new major problems. <i>This
- is not the time to solve additional and unrelated bugs!</i> If no patches are
- merged in, the release is determined to be ready and the release manager may
- move onto the next stage.</p>
-
-</div>
-
-<!-- ======================================================================= -->
-<h3><a name="release-patch">Release Patch Rules</a></h3>
-
-<div>
-
-<p>Below are the rules regarding patching the release branch:</p>
-
-<ol>
- <li><p>Patches applied to the release branch may only be applied by the
- release manager.</p></li>
-
- <li><p>During the first round of testing, patches that fix regressions or that
- are small and relatively risk free (verified by the appropriate code
- owner) are applied to the branch. Code owners are asked to be very
- conservative in approving patches for the branch. We reserve the right to
- reject any patch that does not fix a regression as previously
- defined.</p></li>
-
- <li><p>During the remaining rounds of testing, only patches that fix critical
- regressions may be applied.</p></li>
-</ol>
-
-</div>
-
-<!-- ======================================================================= -->
-<h3><a name="release-final">Release Final Tasks</a></h3>
-
-<div>
-
-<p>The final stages of the release process involves tagging the "final" release
- branch, updating documentation that refers to the release, and updating the
- demo page.</p>
-
-<!-- ======================================================================= -->
-<h4><a name="updocs">Update Documentation</a></h4>
-
-<div>
-
-<p>Review the documentation and ensure that it is up to date. The "Release
- Notes" must be updated to reflect new features, bug fixes, new known issues,
- and changes in the list of supported platforms. The "Getting Started Guide"
- should be updated to reflect the new release version number tag available from
- Subversion and changes in basic system requirements. Merge both changes from
- mainline into the release branch.</p>
-
-</div>
-
-<!-- ======================================================================= -->
-<h4><a name="tag">Tag the LLVM Final Release</a></h4>
-
-<div>
-
-<p>Tag the final release sources using the following procedure:</p>
-
-<div class="doc_code">
-<pre>
-$ svn copy https://llvm.org/svn/llvm-project/llvm/branches/release_XY \
- https://llvm.org/svn/llvm-project/llvm/tags/RELEASE_<i>XY</i>/Final
-
-$ svn copy https://llvm.org/svn/llvm-project/cfe/branches/release_XY \
- https://llvm.org/svn/llvm-project/cfe/tags/RELEASE_<i>XY</i>/Final
-
-$ svn copy https://llvm.org/svn/llvm-project/dragonegg/branches/release_XY \
- https://llvm.org/svn/llvm-project/dragonegg/tags/RELEASE_<i>XY</i>/Final
-
-$ svn copy https://llvm.org/svn/llvm-project/test-suite/branches/release_XY \
- https://llvm.org/svn/llvm-project/test-suite/tags/RELEASE_<i>XY</i>/Final
-</pre>
-</div>
-
-</div>
-
-</div>
-
-<!-- ======================================================================= -->
-<h3><a name="updemo">Update the LLVM Demo Page</a></h3>
-
-<div>
-
-<p>The LLVM demo page must be updated to use the new release. This consists of
- using the new <tt>clang</tt> binary and building LLVM.</p>
-
-<!-- ======================================================================= -->
-<h4><a name="webupdates">Update the LLVM Website</a></h4>
-
-<div>
-
-<p>The website must be updated before the release announcement is sent out. Here
- is what to do:</p>
-
-<ol>
- <li>Check out the <tt>www</tt> module from Subversion.</li>
-
- <li>Create a new subdirectory <tt>X.Y</tt> in the releases directory.</li>
-
- <li>Commit the <tt>llvm</tt>, <tt>test-suite</tt>, <tt>clang</tt> source,
- <tt>clang binaries</tt>, <tt>dragonegg</tt> source, and <tt>dragonegg</tt>
- binaries in this new directory.</li>
-
- <li>Copy and commit the <tt>llvm/docs</tt> and <tt>LICENSE.txt</tt> files
- into this new directory. The docs should be built with
- <tt>BUILD_FOR_WEBSITE=1</tt>.</li>
-
- <li>Commit the <tt>index.html</tt> to the <tt>release/X.Y</tt> directory to
- redirect (use from previous release.</li>
-
- <li>Update the <tt>releases/download.html</tt> file with the new release.</li>
-
- <li>Update the <tt>releases/index.html</tt> with the new release and link to
- release documentation.</li>
-
- <li>Finally, update the main page (<tt>index.html</tt> and sidebar) to point
- to the new release and release announcement. Make sure this all gets
- committed back into Subversion.</li>
-</ol>
-
-</div>
-
-<!-- ======================================================================= -->
-<h4><a name="announce">Announce the Release</a></h4>
-
-<div>
-
-<p>Have Chris send out the release announcement when everything is finished.</p>
-
-</div>
-
-</div>
-
-</div>
-
-<!-- *********************************************************************** -->
-<hr>
-<address>
- <a href="http://jigsaw.w3.org/css-validator/check/referer"><img
- src="http://jigsaw.w3.org/css-validator/images/vcss-blue" alt="Valid CSS"></a>
- <a href="http://validator.w3.org/check/referer"><img
- src="http://www.w3.org/Icons/valid-html401-blue" alt="Valid HTML 4.01"></a>
- <a href="http://llvm.org/">The LLVM Compiler Infrastructure</a>
- <br>
- Last modified: $Date$
-</address>
-</body>
-</html>
Added: llvm/trunk/docs/HowToReleaseLLVM.rst
URL: http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/HowToReleaseLLVM.rst?rev=169608&view=auto
==============================================================================
--- llvm/trunk/docs/HowToReleaseLLVM.rst (added)
+++ llvm/trunk/docs/HowToReleaseLLVM.rst Fri Dec 7 10:42:48 2012
@@ -0,0 +1,504 @@
+=================================
+How To Release LLVM To The Public
+=================================
+
+.. contents::
+ :local:
+
+.. sectionauthor:: Tanya Lattner <tonic at nondot.org>,
+ Reid Spencer <rspencer at x10sys.com>,
+ John Criswell <criswell at cs.uiuc.edu> and
+ Bill Wendling <wendling at apple.com>
+
+Introduction
+============
+
+This document contains information about successfully releasing LLVM ---
+including subprojects: e.g., ``clang`` and ``dragonegg`` --- to the public. It
+is the Release Manager's responsibility to ensure that a high quality build of
+LLVM is released.
+
+.. _timeline:
+
+Release Timeline
+================
+
+LLVM is released on a time based schedule --- roughly every 6 months. We do
+not normally have dot releases because of the nature of LLVM's incremental
+development philosophy. That said, the only thing preventing dot releases for
+critical bug fixes from happening is a lack of resources --- testers,
+machines, time, etc. And, because of the high quality we desire for LLVM
+releases, we cannot allow for a truncated form of release qualification.
+
+The release process is roughly as follows:
+
+* Set code freeze and branch creation date for 6 months after last code freeze
+ date. Announce release schedule to the LLVM community and update the website.
+
+* Create release branch and begin release process.
+
+* Send out release candidate sources for first round of testing. Testing lasts
+ 7-10 days. During the first round of testing, any regressions found should be
+ fixed. Patches are merged from mainline into the release branch. Also, all
+ features need to be completed during this time. Any features not completed at
+ the end of the first round of testing will be removed or disabled for the
+ release.
+
+* Generate and send out the second release candidate sources. Only *critial*
+ bugs found during this testing phase will be fixed. Any bugs introduced by
+ merged patches will be fixed. If so a third round of testing is needed.
+
+* The release notes are updated.
+
+* Finally, release!
+
+.. _process:
+
+Release Process
+===============
+
+#. :ref:`Release Administrative Tasks <release-admin>`
+
+ #. :ref:`Create Release Branch <branch>`
+
+ #. :ref:`Update Version Numbers <verchanges>`
+
+#. :ref:`Building the Release <release-build>`
+
+ #. :ref:`Build the LLVM Source Distribution <dist>`
+
+ #. :ref:`Build LLVM <build>`
+
+ #. :ref:`Build the Clang Binary Distribution <clangbin>`
+
+ #. :ref:`Target Specific Build Details <target-build>`
+
+#. :ref:`Release Qualification Criteria <release-qualify>`
+
+ #. :ref:`Qualify LLVM <llvm-qualify>`
+
+ #. :ref:`Qualify Clang <clang-qualify>`
+
+ #. :ref:`Specific Target Qualification Details <target>`
+
+#. :ref:`Community Testing <commTest>`
+
+#. :ref:`Release Patch Rules <release-patch>`
+
+#. :ref:`Release final tasks <release-final>`
+
+ #. :ref:`Update Documentation <updocs>`
+
+ #. :ref:`Tag the LLVM Final Release <tag>`
+
+ #. :ref:`Update the LLVM Demo Page <updemo>`
+
+ #. :ref:`Update the LLVM Website <webupdates>`
+
+ #. :ref:`Announce the Release <announce>`
+
+.. _release-admin:
+
+Release Administrative Tasks
+----------------------------
+
+This section describes a few administrative tasks that need to be done for the
+release process to begin. Specifically, it involves:
+
+* Creating the release branch,
+
+* Setting version numbers, and
+
+* Tagging release candidates for the release team to begin testing.
+
+.. _branch:
+
+Create Release Branch
+^^^^^^^^^^^^^^^^^^^^^
+
+Branch the Subversion trunk using the following procedure:
+
+#. Remind developers that the release branching is imminent and to refrain from
+ committing patches that might break the build. E.g., new features, large
+ patches for works in progress, an overhaul of the type system, an exciting
+ new TableGen feature, etc.
+
+#. Verify that the current Subversion trunk is in decent shape by
+ examining nightly tester and buildbot results.
+
+#. Create the release branch for ``llvm``, ``clang``, the ``test-suite``, and
+ ``dragonegg`` from the last known good revision. The branch's name is
+ ``release_XY``, where ``X`` is the major and ``Y`` the minor release
+ numbers. The branches should be created using the following commands:
+
+ ::
+
+ $ svn copy https://llvm.org/svn/llvm-project/llvm/trunk \
+ https://llvm.org/svn/llvm-project/llvm/branches/release_XY
+
+ $ svn copy https://llvm.org/svn/llvm-project/cfe/trunk \
+ https://llvm.org/svn/llvm-project/cfe/branches/release_XY
+
+ $ svn copy https://llvm.org/svn/llvm-project/dragonegg/trunk \
+ https://llvm.org/svn/llvm-project/dragonegg/branches/release_XY
+
+ $ svn copy https://llvm.org/svn/llvm-project/test-suite/trunk \
+ https://llvm.org/svn/llvm-project/test-suite/branches/release_XY
+
+#. Advise developers that they may now check their patches into the Subversion
+ tree again.
+
+#. The Release Manager should switch to the release branch, because all changes
+ to the release will now be done in the branch. The easiest way to do this is
+ to grab a working copy using the following commands:
+
+ ::
+
+ $ svn co https://llvm.org/svn/llvm-project/llvm/branches/release_XY llvm-X.Y
+
+ $ svn co https://llvm.org/svn/llvm-project/cfe/branches/release_XY clang-X.Y
+
+ $ svn co https://llvm.org/svn/llvm-project/dragonegg/branches/release_XY dragonegg-X.Y
+
+ $ svn co https://llvm.org/svn/llvm-project/test-suite/branches/release_XY test-suite-X.Y
+
+.. _verchanges:
+
+Update LLVM Version
+^^^^^^^^^^^^^^^^^^^
+
+After creating the LLVM release branch, update the release branches'
+``autoconf`` and ``configure.ac`` versions from '``X.Ysvn``' to '``X.Y``'.
+Update it on mainline as well to be the next version ('``X.Y+1svn``').
+Regenerate the configure scripts for both ``llvm`` and the ``test-suite``.
+
+In addition, the version numbers of all the Bugzilla components must be updated
+for the next release.
+
+.. _dist:
+
+Build the LLVM Release Candidates
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Create release candidates for ``llvm``, ``clang``, ``dragonegg``, and the LLVM
+``test-suite`` by tagging the branch with the respective release candidate
+number. For instance, to create **Release Candidate 1** you would issue the
+following commands:
+
+::
+
+ $ svn mkdir https://llvm.org/svn/llvm-project/llvm/tags/RELEASE_XY
+ $ svn copy https://llvm.org/svn/llvm-project/llvm/branches/release_XY \
+ https://llvm.org/svn/llvm-project/llvm/tags/RELEASE_XY/rc1
+
+ $ svn mkdir https://llvm.org/svn/llvm-project/cfe/tags/RELEASE_XY
+ $ svn copy https://llvm.org/svn/llvm-project/cfe/branches/release_XY \
+ https://llvm.org/svn/llvm-project/cfe/tags/RELEASE_XY/rc1
+
+ $ svn mkdir https://llvm.org/svn/llvm-project/dragonegg/tags/RELEASE_XY
+ $ svn copy https://llvm.org/svn/llvm-project/dragonegg/branches/release_XY \
+ https://llvm.org/svn/llvm-project/dragonegg/tags/RELEASE_XY/rc1
+
+ $ svn mkdir https://llvm.org/svn/llvm-project/test-suite/tags/RELEASE_XY
+ $ svn copy https://llvm.org/svn/llvm-project/test-suite/branches/release_XY \
+ https://llvm.org/svn/llvm-project/test-suite/tags/RELEASE_XY/rc1
+
+Similarly, **Release Candidate 2** would be named ``RC2`` and so on. This keeps
+a permanent copy of the release candidate around for people to export and build
+as they wish. The final released sources will be tagged in the ``RELEASE_XY``
+directory as ``Final`` (c.f. :ref:`Tag the LLVM Final Release <tag>`).
+
+The Release Manager may supply pre-packaged source tarballs for users. This can
+be done with the following commands:
+
+::
+
+ $ svn export https://llvm.org/svn/llvm-project/llvm/tags/RELEASE_XY/rc1 llvm-X.Yrc1
+ $ svn export https://llvm.org/svn/llvm-project/cfe/tags/RELEASE_XY/rc1 clang-X.Yrc1
+ $ svn export https://llvm.org/svn/llvm-project/dragonegg/tags/RELEASE_XY/rc1 dragonegg-X.Yrc1
+ $ svn export https://llvm.org/svn/llvm-project/test-suite/tags/RELEASE_XY/rc1 llvm-test-X.Yrc1
+
+ $ tar -cvf - llvm-X.Yrc1 | gzip > llvm-X.Yrc1.src.tar.gz
+ $ tar -cvf - clang-X.Yrc1 | gzip > clang-X.Yrc1.src.tar.gz
+ $ tar -cvf - dragonegg-X.Yrc1 | gzip > dragonegg-X.Yrc1.src.tar.gz
+ $ tar -cvf - llvm-test-X.Yrc1 | gzip > llvm-test-X.Yrc1.src.tar.gz
+
+.. _release-build:
+
+Building the Release
+--------------------
+
+The builds of ``llvm``, ``clang``, and ``dragonegg`` *must* be free of
+errors and warnings in Debug, Release+Asserts, and Release builds. If all
+builds are clean, then the release passes Build Qualification.
+
+The ``make`` options for building the different modes:
+
++-----------------+---------------------------------------------+
+| Mode | Options |
++=================+=============================================+
+| Debug | ``ENABLE_OPTIMIZED=0`` |
++-----------------+---------------------------------------------+
+| Release+Asserts | ``ENABLE_OPTIMIZED=1`` |
++-----------------+---------------------------------------------+
+| Release | ``ENABLE_OPTIMIZED=1 DISABLE_ASSERTIONS=1`` |
++-----------------+---------------------------------------------+
+
+
+.. _build:
+
+Build LLVM
+^^^^^^^^^^
+
+Build ``Debug``, ``Release+Asserts``, and ``Release`` versions
+of ``llvm`` on all supported platforms. Directions to build ``llvm``
+are :ref:`here <getting_started>`.
+
+.. _clangbin:
+
+Build Clang Binary Distribution
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Creating the ``clang`` binary distribution (Debug/Release+Asserts/Release)
+requires performing the following steps for each supported platform:
+
+#. Build clang according to the directions `here
+ <http://clang.llvm.org/get_started.html>`__.
+
+#. Build both a Debug and Release version of clang. The binary will be the
+ Release build.
+
+#. Package ``clang`` (details to follow).
+
+.. _target-build:
+
+Target Specific Build Details
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The table below specifies which compilers are used for each Arch/OS combination
+when qualifying the build of ``llvm``, ``clang``, and ``dragonegg``.
+
++--------------+---------------+----------------------+
+| Architecture | OS | compiler |
++==============+===============+======================+
+| x86-32 | Mac OS 10.5 | gcc 4.0.1 |
++--------------+---------------+----------------------+
+| x86-32 | Linux | gcc 4.2.X, gcc 4.3.X |
++--------------+---------------+----------------------+
+| x86-32 | FreeBSD | gcc 4.2.X |
++--------------+---------------+----------------------+
+| x86-32 | mingw | gcc 3.4.5 |
++--------------+---------------+----------------------+
+| x86-64 | Mac OS 10.5 | gcc 4.0.1 |
++--------------+---------------+----------------------+
+| x86-64 | Linux | gcc 4.2.X, gcc 4.3.X |
++--------------+---------------+----------------------+
+| x86-64 | FreeBSD | gcc 4.2.X |
++--------------+---------------+----------------------+
+
+.. _release-qualify:
+
+Release Qualification Criteria
+------------------------------
+
+A release is qualified when it has no regressions from the previous release (or
+baseline). Regressions are related to correctness first and performance second.
+(We may tolerate some minor performance regressions if they are deemed
+necessary for the general quality of the compiler.)
+
+**Regressions are new failures in the set of tests that are used to qualify
+each product and only include things on the list. Every release will have
+some bugs in it. It is the reality of developing a complex piece of
+software. We need a very concrete and definitive release criteria that
+ensures we have monotonically improving quality on some metric. The metric we
+use is described below. This doesn't mean that we don't care about other
+criteria, but these are the criteria which we found to be most important and
+which must be satisfied before a release can go out.**
+
+.. _llvm-qualify:
+
+Qualify LLVM
+^^^^^^^^^^^^
+
+LLVM is qualified when it has a clean test run without a front-end. And it has
+no regressions when using either ``clang`` or ``dragonegg`` with the
+``test-suite`` from the previous release.
+
+.. _clang-qualify:
+
+Qualify Clang
+^^^^^^^^^^^^^
+
+``Clang`` is qualified when front-end specific tests in the ``llvm`` dejagnu
+test suite all pass, clang's own test suite passes cleanly, and there are no
+regressions in the ``test-suite``.
+
+.. _target:
+
+Specific Target Qualification Details
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
++--------------+-------------+----------------+-----------------------------+
+| Architecture | OS | clang baseline | tests |
++==============+=============+================+=============================+
+| x86-32 | Linux | last release | llvm dejagnu, |
+| | | | clang tests, |
+| | | | test-suite (including spec) |
++--------------+-------------+----------------+-----------------------------+
+| x86-32 | FreeBSD | last release | llvm dejagnu, |
+| | | | clang tests, |
+| | | | test-suite |
++--------------+-------------+----------------+-----------------------------+
+| x86-32 | mingw | none | QT |
++--------------+-------------+----------------+-----------------------------+
+| x86-64 | Mac OS 10.X | last release | llvm dejagnu, |
+| | | | clang tests, |
+| | | | test-suite (including spec) |
++--------------+-------------+----------------+-----------------------------+
+| x86-64 | Linux | last release | llvm dejagnu, |
+| | | | clang tests, |
+| | | | test-suite (including spec) |
++--------------+-------------+----------------+-----------------------------+
+| x86-64 | FreeBSD | last release | llvm dejagnu, |
+| | | | clang tests, |
+| | | | test-suite |
++--------------+-------------+----------------+-----------------------------+
+
+.. _commTest:
+
+Community Testing
+-----------------
+
+Once all testing has been completed and appropriate bugs filed, the release
+candidate tarballs are put on the website and the LLVM community is notified.
+Ask that all LLVM developers test the release in 2 ways:
+
+#. Download ``llvm-X.Y``, ``llvm-test-X.Y``, and the appropriate ``clang``
+ binary. Build LLVM. Run ``make check`` and the full LLVM test suite (``make
+ TEST=nightly report``).
+
+#. Download ``llvm-X.Y``, ``llvm-test-X.Y``, and the ``clang`` sources. Compile
+ everything. Run ``make check`` and the full LLVM test suite (``make
+ TEST=nightly report``).
+
+Ask LLVM developers to submit the test suite report and ``make check`` results
+to the list. Verify that there are no regressions from the previous release.
+The results are not used to qualify a release, but to spot other potential
+problems. For unsupported targets, verify that ``make check`` is at least
+clean.
+
+During the first round of testing, all regressions must be fixed before the
+second release candidate is tagged.
+
+If this is the second round of testing, the testing is only to ensure that bug
+fixes previously merged in have not created new major problems. *This is not
+the time to solve additional and unrelated bugs!* If no patches are merged in,
+the release is determined to be ready and the release manager may move onto the
+next stage.
+
+.. _release-patch:
+
+Release Patch Rules
+-------------------
+
+Below are the rules regarding patching the release branch:
+
+#. Patches applied to the release branch may only be applied by the release
+ manager.
+
+#. During the first round of testing, patches that fix regressions or that are
+ small and relatively risk free (verified by the appropriate code owner) are
+ applied to the branch. Code owners are asked to be very conservative in
+ approving patches for the branch. We reserve the right to reject any patch
+ that does not fix a regression as previously defined.
+
+#. During the remaining rounds of testing, only patches that fix critical
+ regressions may be applied.
+
+.. _release-final:
+
+Release Final Tasks
+-------------------
+
+The final stages of the release process involves tagging the "final" release
+branch, updating documentation that refers to the release, and updating the
+demo page.
+
+.. _updocs:
+
+Update Documentation
+^^^^^^^^^^^^^^^^^^^^
+
+Review the documentation and ensure that it is up to date. The "Release Notes"
+must be updated to reflect new features, bug fixes, new known issues, and
+changes in the list of supported platforms. The "Getting Started Guide" should
+be updated to reflect the new release version number tag available from
+Subversion and changes in basic system requirements. Merge both changes from
+mainline into the release branch.
+
+.. _tag:
+
+Tag the LLVM Final Release
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Tag the final release sources using the following procedure:
+
+::
+
+ $ svn copy https://llvm.org/svn/llvm-project/llvm/branches/release_XY \
+ https://llvm.org/svn/llvm-project/llvm/tags/RELEASE_XY/Final
+
+ $ svn copy https://llvm.org/svn/llvm-project/cfe/branches/release_XY \
+ https://llvm.org/svn/llvm-project/cfe/tags/RELEASE_XY/Final
+
+ $ svn copy https://llvm.org/svn/llvm-project/dragonegg/branches/release_XY \
+ https://llvm.org/svn/llvm-project/dragonegg/tags/RELEASE_XY/Final
+
+ $ svn copy https://llvm.org/svn/llvm-project/test-suite/branches/release_XY \
+ https://llvm.org/svn/llvm-project/test-suite/tags/RELEASE_XY/Final
+
+.. _updemo:
+
+Update the LLVM Demo Page
+-------------------------
+
+The LLVM demo page must be updated to use the new release. This consists of
+using the new ``clang`` binary and building LLVM.
+
+.. _webupdates:
+
+Update the LLVM Website
+^^^^^^^^^^^^^^^^^^^^^^^
+
+The website must be updated before the release announcement is sent out. Here
+is what to do:
+
+#. Check out the ``www`` module from Subversion.
+
+#. Create a new subdirectory ``X.Y`` in the releases directory.
+
+#. Commit the ``llvm``, ``test-suite``, ``clang`` source, ``clang binaries``,
+ ``dragonegg`` source, and ``dragonegg`` binaries in this new directory.
+
+#. Copy and commit the ``llvm/docs`` and ``LICENSE.txt`` files into this new
+ directory. The docs should be built with ``BUILD_FOR_WEBSITE=1``.
+
+#. Commit the ``index.html`` to the ``release/X.Y`` directory to redirect (use
+ from previous release).
+
+#. Update the ``releases/download.html`` file with the new release.
+
+#. Update the ``releases/index.html`` with the new release and link to release
+ documentation.
+
+#. Finally, update the main page (``index.html`` and sidebar) to point to the
+ new release and release announcement. Make sure this all gets committed back
+ into Subversion.
+
+.. _announce:
+
+Announce the Release
+^^^^^^^^^^^^^^^^^^^^
+
+Have Chris send out the release announcement when everything is finished.
+
Modified: llvm/trunk/docs/development_process.rst
URL: http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/development_process.rst?rev=169608&r1=169607&r2=169608&view=diff
==============================================================================
--- llvm/trunk/docs/development_process.rst (original)
+++ llvm/trunk/docs/development_process.rst Fri Dec 7 10:42:48 2012
@@ -9,6 +9,7 @@
MakefileGuide
Projects
LLVMBuild
+ HowToReleaseLLVM
* :ref:`projects`
@@ -26,6 +27,6 @@
Describes how the LLVM makefiles work and how to use them.
-* `How To Release LLVM To The Public <HowToReleaseLLVM.html>`_
+* :doc:`HowToReleaseLLVM`
This is a guide to preparing LLVM releases. Most developers can ignore it.
More information about the llvm-commits
mailing list