Author: brett
Date: Thu Jun 2 17:26:21 2005
New Revision: 179682
URL: http://svn.apache.org/viewcvs?rev=179682&view=rev
Log:
PR: MAVEN-1611
Submitted by: Robert Burrell Donkin
Reviewed by: Brett Porter
improvements to the text of the release document
Modified:
maven/maven-1/core/trunk/xdocs/using/releasing.xml
Modified: maven/maven-1/core/trunk/xdocs/using/releasing.xml
URL:
http://svn.apache.org/viewcvs/maven/maven-1/core/trunk/xdocs/using/releasing.xml?rev=179682&r1=179681&r2=179682&view=diff
==============================================================================
--- maven/maven-1/core/trunk/xdocs/using/releasing.xml (original)
+++ maven/maven-1/core/trunk/xdocs/using/releasing.xml Thu Jun 2 17:26:21 2005
@@ -27,35 +27,41 @@
<body>
<section name="Making Releases">
<p>
- Maven can simplify several areas of the release process for software,
but it is always worth having a process
- in order.
+ Maven can simplify several areas of the release process for software
but it cannot substitute for
+ planning. Think about the process before starting any release.
</p>
<subsection name="Determine Format">
<p>
- Firstly, you must decide what format you will be distributing your
software in. For example:
+ Firstly, you must decide what form your distribution will take. For
example:
</p>
<ul>
- <li>Standalone library</li>
+ <li>Standalone library artifact</li>
<li>Binary and source distributions</li>
<li>Installer</li>
</ul>
<p>
- If you are distributing your artifact as is, you can use the
existing deployment goals (as discussed in
- <a
href="../reference/internal-repositories.html#Deploying_to_the_Internal_Repository">Deploying
to the
- Internal Repository</a>).
+ Once you have decided: it's time to set up maven.
</p>
<p>
- For binary and source archives, see the
+ If you plan to distribute your normal artifact as is then use the
existing deployment goals. See
+ <a
href="../reference/internal-repositories.html#Deploying_to_the_Internal_Repository">
+ Deploying to the Internal Repository</a> for discussions about
distributing raw artifacts.
+ Public releases (of course) require deployment to a public repository.
+ If your usual internal repository is private (and you want to use
maven to upload the artifacts)
+ then some changes to your project's properties may be needed for the
release.
+ </p>
+ <p>
+ Distributions as binary and source archives are supported by the
<a href="../reference/plugins/dist/">distribution plugin</a>.
For installers, currently, Maven only supports the NSIS installer on
Windows.
See the
- <a href="../reference/nsis/">NSIS plugin</a> for information.
- In both cases, some configuration will be necessary. You may have to
do additional scripting to get the
+ <a href="../reference/plugins/nsis/">NSIS plugin</a> for information.
+ In both cases, some configuration will be necessary. You may have to
add extra scripting to get the
release just as you want it.
</p>
<p>
- Once you have decided on one or more formats and have tested being
able to generate a release, you are ready
- to go, and this won't need to be changed in the future.
+ It may take a little effort to create and test release generation but
it only needs to be done once.
+ Maven will then be able reliable to generate all future releases to
this format.
</p>
</subsection>
<subsection name="Check Dependencies">
@@ -64,18 +70,20 @@
<a href="bestpractices.html#Reproduciblity">Best Practices</a> for
more).
</p>
<p>
- You should check the dependencies of the project you will be
releasing to ensure that all dependencies on
- snapshots or other non-final releases are resolved to proper
releases and that the software is tested against
- them.
+ You should check the dependencies of the project you will be
releasing. Ensure that all dependencies on
+ snapshots or other non-final releases are resolved to proper releases.
+ Then test that the software runs correct against them.
</p>
<p>
- If you remain pointing to a development dependency that is later
overwritten, attempting to rebuild your
- release may lead to at best a different result, at worst a failure
to build.
+ Releasing against a development dependency may lead to problems later.
+ Not only may this cause future compatibility problems for your users
but if you remain pointing to a development
+ dependency that is later overwritten, attempting to rebuild your
+ release may lead to at best a different result, at worst a failure to
build.
</p>
<p>
- If there is no release of the software, but you know the current
development build to be stable, as a last
- resort you should internally release that library, using the current
time as a version, or similar that will
- not be overwritten.
+ If there is no release of the software, but you know the current
development build to be stable, as a last
+ resort you should internally release that library (using the current
time as a version, or similar).
+ At least then your software has a concrete dependency that should not
be overwritten.
</p>
<p>
Future Maven release tools will help to identify the existence of
such snapshots and help to resolve them,
@@ -84,16 +92,17 @@
</subsection>
<subsection name="Utilise Source Control">
<p>
- If you are using a source control system, make sure to tag the
release so that it can be built cleanly from
- the system. Maven can provide assistance with this.
+ If you are using a source control system, the release should be
cleanly built from a tag
+ (so that the release codebase is clearly known). So, the SCM needs to
be tagged before the release is cut.
+ Maven can provide assistance with this.
</p>
<p>
- Currently, the only automated release mechanism in Maven is that
provided by the SCM plugin.
+ Currently, the only automated release mechanism in Maven for cutting
releases is provided by the SCM plugin.
Please refer to the documentation on
<a href="../reference/plugins/scm/releasing.html">Making Releases
from SCM</a>.
</p>
<p>
- The SCM plugin performs a release in two steps:
+ The SCM plugin cuts a release in two steps:
</p>
<ol>
<li>preparation - where the descriptors are updated, committed and
the code is tagged</li>
@@ -101,24 +110,41 @@
using the distribution goals you selected in the first
section.</li>
</ol>
</subsection>
- <subsection name="Perform the Release">
+ <subsection name="Cutting the Release">
+ <p>
+ As discussed previously, if you are using an SCM, you should utilise
the SCM plugin to do this as this will
+ ensure a build against a clean checkout. Ideally you should also build
in a known environment each time.
+ Pay attention to the version of Java used to compile the release: some
bytecode produced by later versions
+ may be incompatible with earlier versions. Look out for warnings
provided by maven about this.
+ </p>
<p>
- With everything together, performing the release is quite simple. If
the plugin supports it, you can deploy
- the released artifact directly to the repository.
+ With everything together and prepared, cutting the release is quite
simple (whether the project uses SCM or not).
+ If the plugin supports it, you can deploy the released artifact
directly to the repository.
</p>
+
<p>
- As discussed previously, if you are using an SCM, you should utilise
the SCM plugin to do this, as it will
- build in a clean checkout. Ideally you should also build in a known
environment each time.
+ While Maven will currently create and deploy an MD5 checksum along
with your distribution, this is only useful for verifying
+ download integrity when the sum can be download from a trusted
repository.
+ In many environments (including where there is public distribution
over the internet) it is therefore
+ recommended that additional measures be put in place to allow the
authenticity of the release to be verified.
</p>
<p>
- While Maven will currently deploy an MD5 checksum along with your
distribution, this is only used to verify
- download integrity. In many environments where there is public
distribution over the internet, it is
- recommended that additional security be put in place to verify the
authenticity of the release.
+ It is therefore recommended that (in these cases), an <a
href='http://www.ietf.org/html.charters/openpgp-charter.html'>OpenPGP</a>
+ compatible digital signature is also created.
+ The original signatures and (most importantly) the public keys used to
sign the releases
+ should be held on a tightly secured central server.
+ (Most users will need to download the public key but may not be able
to verify it using the
+ <a href='http://www.gnupg.org/gph/en/manual.html#AEN385'>web of
trust</a>.
+ It is therefore vital that they can download the key from a secure
server.)
+ The public key should also be made available through a public key
server (for example,
+ <a href='http://pgp.mit.edu'>the MIT key server</a>) and efforts made
to link it strongly into the web of trust.
+ It is of crucial importance that all private keys used to sign
releases be kept
+ <a href='http://www.gnupg.org/gph/en/manual.html#AEN513'>secure</a>.
</p>
<p>
- While Maven does not currently support automatically generating it,
it is recommended that you sign your
- release using GPG, and provide the original signatures only on the
tightly secured central server, instead of
- on distribution mirrors.
+ Since Maven does not currently support automatically generating
digital signatures,
+ it is recommended that you sign your release using <a
href='http://www.gnupg.org'>GPG</a>
+ (or some other OpenPGP compatible application).
</p>
</subsection>
<subsection name="Republish the Site">
@@ -129,7 +155,9 @@
</subsection>
<subsection name="Announce the Release">
<p>
- Finally, after the release is out, checked, and propogated to the
mirrors, you will want to make announcements.
+ Finally, after the release is out and checked, you will want to make
announcements to tell the world
+ about it. Here again, maven can help. (If you are using a
sophisticated distribution system with mirroring,
+ you should wait until the mirrors have sync'd before making the
annoucements.)
</p>
<p>
If you are maintaining a change record, you can use the
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
