You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@maven.apache.org by br...@apache.org on 2005/06/03 02:26:21 UTC
svn commit: r179682 - /maven/maven-1/core/trunk/xdocs/using/releasing.xml
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: dev-unsubscribe@maven.apache.org
For additional commands, e-mail: dev-help@maven.apache.org