You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@maven.apache.org by jv...@apache.org on 2005/11/17 17:02:53 UTC
svn commit: r345273 -
/maven/site/trunk/src/site/apt/guides/mini/guide-releasing.apt
Author: jvanzyl
Date: Thu Nov 17 08:02:49 2005
New Revision: 345273
URL: http://svn.apache.org/viewcvs?rev=345273&view=rev
Log:
o http://jira.codehaus.org/browse/MNG-1564
Modified:
maven/site/trunk/src/site/apt/guides/mini/guide-releasing.apt
Modified: maven/site/trunk/src/site/apt/guides/mini/guide-releasing.apt
URL: http://svn.apache.org/viewcvs/maven/site/trunk/src/site/apt/guides/mini/guide-releasing.apt?rev=345273&r1=345272&r2=345273&view=diff
==============================================================================
--- maven/site/trunk/src/site/apt/guides/mini/guide-releasing.apt (original)
+++ maven/site/trunk/src/site/apt/guides/mini/guide-releasing.apt Thu Nov 17 08:02:49 2005
@@ -1,81 +1,268 @@
- -----
- Guide to Releasing
+-----
+ Guide to using the release plugin
-----
Jason van Zyl
+ Trent Rosenbaum
-----
- 12 October 2005
+ 14 November 2005
-----
-~~ integrate releasing document
-
Releasing
- The release plugin provides some basic functionality for making releases, and updating
- the project SCM accordingly. A release is performed in 2 steps:
+* Introduction
+
+ The main aim of the maven-release plugin is to provide a standard mechanism to release
+ project artifacts outside the immediate development team. The plugin provides basic functionality to create
+ a release and to update the project's SCM accordingly.
+
+ To create a release the maven-release plugin is executed through maven in 2 stages:
[[1]] Preparing the release.
[[2]] Performing the release.
[]
+
+* Preparing the release
-Preparing the release
-
- The <<<release:prepare>>> goal will:
+ The plugin will record release information into a new revision of the project's <pom.xml> file as well as
+ applying SCM versioning to the project's resources.
- [[1]] Verify that there are no uncommitted changes in the checkout
+ The <<<release:prepare>>> goal will:
+
+ [[1]] Verify that there are no uncommitted changes in the workspace.
- [[2]] Prompt for a desired version and tag name
+ [[2]] Prompt the user for the desired tag, release and development version names.
- [[3]] Modify the pom.xml
+ [[3]] Modify and commit release information into the <pom.xml> file.
+
+ [[4]] Tag the entire project source tree with the new tag name.
- [[4]] Tag the entire source tree with the new tag name
-
[]
+ The following example shows how to run the <<<release:prepare>>> goal with a Subversion SCM. The commandline example directs the plugin to
+ locate a Subversion SCM on a local file system.
+
+
-----
-mvn release:prepare -DtagBase=svn+ssh://svn.codehaus.org/home/projects/plexus/scm/tags
+mvn release:prepare \
+ -Dproject.scm.developerConnection=scm:svn:file:///D:/subversion_data/repos/my_repo/my-app-example/trunk \
+ -DtagBase=file:///D:/subversion_data/repos/my_repo/my-app-example/tags
-----
- When this operation is over, your source control has the released code tagged and ready to deploy.
-Performing the release
+ When using the <<<release:prepare>>> goal, the user must supply maven with information regarding the current location of the project's SCM.
+ In the previous example maven was supplied with the current location of the development trunk and the new location to record tagged instances of the project.
+ * <<project.scm.developerConnection>>
+
+ The current location of the development trunk. A valid SCM URL format appropriate to the SCM provider. The "SCM:Provider:" prefix is used to determine the provider being used.
+
+ * <<tagbase>>
+
+ The new location to record a tagged release. A valid SCM URL format appropriate to the SCM provider without the "SCM:Provider:" prefix.
+
+ []
+
+ The previous goal parameters can be supplied while executing maven on the commandline, (as shown in the previous example)
+ or they can be defined and maintained within the project's <pom.xml> file. The location of the current development trunk is defined
+ within the <pom.xml> file in the following form:
+
+-----
+<project>
+ <modelVersion>4.0.0</modelVersion>
+ <groupId>com.mycompany.app</groupId>
+ <artifactId>app</artifactId>
+ <packaging>jar</packaging>
+ <version>1.0-SNAPSHOT</version>
+ <name>Application</name>
+ <url>http://app.mycompany.com</url>
+ ...
+ <scm>
+ <developerConnection>scm:svn:file:///D:/subversion_data/repos/my_repo/my-app-example/trunk</developerConnection>
+ </scm>
+ ...
+ <build>
+ <plugins>
+ ...
+ <plugin>
+ <artifactId>maven-release-plugin</artifactId>
+ <configuration>
+ ...
+ <tagBase>
+ file:///D:/subversion_data/repos/my_repo/my-app-example/tags
+ </tagBase>
+ ...
+ </configuration>
+ </plugin>
+ ...
+ </plugins>
+ </build>
+ ...
+</project>
-----
-mvn release:perform -DtagBase=svn+ssh://svn.codehaus.org/home/projects/plexus/scm
+
+ To define the tagBase parameter within the <pom.xml> file a tagBase element must be defined within a <plugins/plugin/configuration> element.
+ The following example shows how this would look within the <pom.xml> file.
+
+-----
+<project>
+ <modelVersion>4.0.0</modelVersion>
+ <groupId>com.mycompany.app</groupId>
+ <artifactId>app</artifactId>
+ <packaging>jar</packaging>
+ <version>1.0-SNAPSHOT</version>
+ <name>Application</name>
+ <url>http://app.mycompany.com</url>
+ ...
+ <scm>
+ <developerConnection>scm:svn:file:///D:/subversion_data/repos/my_repo/my-app-example/trunk</developerConnection>
+ </scm>
+ ...
+ <build>
+ <plugins>
+ ...
+ <plugin>
+ <artifactId>maven-release-plugin</artifactId>
+ <configuration>
+ ...
+ <tagBase>
+ file:///D:/subversion_data/repos/my_repo/my-app-example/tags
+ </tagBase>
+ ...
+ </configuration>
+ </plugin>
+ ...
+ </plugins>
+ </build>
+ ...
+</project>
-----
-~~ -----
-~~ o had to update each component manually to change the version
-~~ o had to change the depMan element in the top-level POM
-~~ both tedious and error prone
-~~ o had to change the assembly file name
-~~ o had to change the webpapp file name
+ During the execution of the <<<release:prepare>>> goal maven will interact with the user to gather information about the current release.
+ Maven will prompt the user for the following information:
+
+ * <<A Desired SCM provider tag name>>.
+
+ This is a SCM provider specific value, in the case of the Subversion SCM provider this value
+ is equal to the folder name that will appear under the URL provided by the the tagBase parameter.
+
+ * <<A Desired project release version>>.
+
+ This value is placed in the <pom.xml> that will define the current release. If a development <pom.xml> holds a version value of 1.0-SNAPSHOT
+ then the release version would be 1.0. This is not enforced and can be a value appropriate to yourself or a company environment.
+
+ * <<A New development version>>.
+
+ This value is the placed in the next revision of the <pom.xml> file used for continuing development. If the current
+ release represented version 1.0 then an appropriate value could be 2.0-SNAPSHOT. The SNAPSHOT designator is required to prepare and
+ perform future releases. This value is then committed in the next development revision of the <pom.xml> file.
+
+ []
+
+ After maven has been supplied with the required information the maven-release plugin will interact with the project's
+ SCM and define a relese to be extracted and deployed. At the same time the project's development trunk is updated allowing developers
+ to continue with further modifications that will be included within future releases.
+
+
+* Performing the release
-~~ sign the release
+ The plugin will extract file revisions associated with the current release. Maven will compile, test and package the versioned project
+ source code into an artifact. The final deliverable will then be released into an appropriate maven repository.
+ The <<<release:perform>>> goal will:
+
+ [[1]] Extract file revisions versioned under the new tag name.
+
+ [[2]] Execute the maven build lifecycle on the extracted instance of the project.
+
+ [[3]] Deploy the versioned artifacts to appropriate local and remote repositories.
+
+ []
+
+ The following example shows how to run the <<<release:perform>>> goal from the commandline.
+
+-----
+mvn release:perform
-----
-#!/bin/sh
+
+ The <<<release:perform>>> goal requires a file called <release.properties> to be present within the project root directory.
+ The <release.properties> file is constructed during the execution of the <<<release:prepare>>> goal and contains all the information
+ needed to locate and extract the correctly tagged version of the project. Shown below is an example of the contents that can
+ appear within an instance of the <release.properties> file.
-rel=$1
+ <<Note:>> The location of the <release.properties> file is under review and could be moved to the target directory.
-if [ -z "$rel" ]; then
- echo usage: $0 release
- exit 1
- fi
-
- exts="tar.gz tar.bz2 zip"
- if [ -f "$rel.exe" ]; then
- exts="$exts exe"
- fi
-
- for i in $exts; do md5sum $rel.$i | sed 's/ .*$//g' >$rel.$i.md5; done
-
- for i in $exts; do gpg --armor --output $rel.$i.asc --detach-sig
-$rel.$i; done
+-----
+#Generated by Release Plugin on: Sat Nov 12 11:22:33 GMT 2005
+#Sat Nov 12 11:22:33 GMT 2005
+maven.username=myusername
+checkpoint.transformed-pom-for-release=OK
+scm.tag=1.0
+scm.url=scm\:svn\:file\:///D\:/subversion_data/repos/my_repo/my-app-example/trunk
+scm.tag-base=file\:///D\:/subversion_data/repos/my_repo/my-app-example/tags
+checkpoint.transform-pom-for-development=OK
+checkpoint.local-modifications-checked=OK
+checkpoint.initialized=OK
+checkpoint.checked-in-release-version=OK
+checkpoint.tagged-release=OK
+checkpoint.prepared-release=OK
+checkpoint.check-in-development-version=OK
-----
-~~ o deploy to /www/www.apache.org/dist/maven/binaries
+ The <release.properties> file is created while preparing the release. After performing the release the file remains within the project root
+ directory until the maven user deletes it. The <release.properties> file can be given to any developer within the team and
+ by simply excuting the <<<release:perform>>> goal can create and deploy a new instance of the project artifact time and again.
+
+ During the execution of the <<<release:perform>>> goal the entire maven build lifecycle is executed on the project.
+ The tagged project source code is extracted, compiled, tested, documented and deployed. An instance of the release artifact is deployed
+ to the machine's local repository. An another instance of the release can be deployed to a remote repository by configuring the
+ <distributionManagement> element within the <pom.xml> file.
+
+ The following is an example of how a distributionManagement element can be configured within a project <pom.xml> file.
+
+-----
+<project>
+ <modelVersion>4.0.0</modelVersion>
+ <groupId>com.mycompany.app</groupId>
+ <artifactId>app</artifactId>
+ <packaging>jar</packaging>
+ <version>1.0-SNAPSHOT</version>
+ <name>Application</name>
+ <url>http://app.mycompany.com</url>
+ ...
+ <distributionManagement>
+ <repository>
+ <id>myRepoId</id>
+ <name>myCompanyReporsitory</name>
+ <url>ftp://repository.mycompany.com/repository</url>
+ </repository>
+ </distributionManagement>
+ ...
+</project>
+-----
-~~ o even though we have said each module needs to specify its own version that
-~~ is really a pita. maybe there is a better way we can deal with that.
+ If the distributionManagement element is not configured within the <pom.xml> file then the deployment of the artifact will fail. Maven will
+ report a failure back to the user for the execution of the maven-deploy plugin. Please refer maven documentationa and additional mini
+ guides for the use of the maven-deploy plugin.
+
+ The following delvierables are created and deployed to local and remoted repositories after the execution of the <<<release:perform>>> goal has finished.
+
+ * <artifact id>-<version>.jar
+
+ The binaries for the current release of the project.
+
+ * <artifact id>-<version>-javadoc.jar
+
+ The javadoc explaining the current functionality of the classes within the current release.
+
+ * <artifact id>-<version>-source.jar
+
+ The source code revisions used to build the current release of the project.
+
+ * <artifact id>-<version>.pom
+
+ The contents of the <pom.xml> file used to create the current release of the project.
+
+ []
+
Re: svn commit: r345273
- /maven/site/trunk/src/site/apt/guides/mini/guide-releasing.apt
Posted by Jason van Zyl <ja...@maven.org>.
On Sun, 2005-11-20 at 10:06 +1100, Brett Porter wrote:
> Jason van Zyl wrote:
> > I've tried to relieve the tedium and try to provide more accurate and
> > useful information for the history and easier linking of information. To
> > that end there is now a little script here:
>
> That's great - I'll try it out.
>
> Can we agree on a template? I notice they you are doing a couple of
> things that still get annoying for me:
> - the horizontal lines which are not fun to type without the tool, and
> which clutter the svn log command output which also uses horizontal
> lines. I'm sure it will also look a bit much in the changelog report
That's no problem, I was just reusing the format the JIRA spot spits out
and I was just giving it a whirl. It's definitely a bit much and easy to
remove.
> - the URL: its easy enough to paste the issue in to the search box of an
> already open jira window, and the URLs are likely to rot
> (jira.werken.com -> jira.codehaus.org -> jira.wheredowegonext.org)
When I was playing around I just found it convenient when spitting out
the history to just be able to jump to the issue. I imagine the same
would be true in a generated changelog. The URLs may rot, but for the
most part I don't think it can hurt and at the very least can be
optional. I found it handy myself to jump from email right to the issue.
> I thought we'd decided, and its documented here:
> http://maven.apache.org/guides/development/guide-m2-development.html#Commit%20Message%20Template
Sure, but I think that can be adjusted to allow for richer information
if it's available. I'm just trying to provide better navigation when the
information is available. I like seeing the URL and the description as
it provides an easier way to navigate and an easier way to understand
what you're looking at.
I can easily change to use PR and Submitter, though it is nice to see
the reporter as well even when there isn't a patch suppled (and usually
they are the same when a patch is supplied). It would be nice to have
their email at hand but I refrained from adding it because of the spam
potential.
That said I will try to get it wired in on the server side so it's
convenient and provides a richer set of information for which there are
any number of possibilities.
--
jvz.
Jason van Zyl
jason at maven.org
http://maven.apache.org
believe nothing, no matter where you read it,
or who has said it,
not even if i have said it,
unless it agrees with your own reason
and your own common sense.
-- Buddha
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
For additional commands, e-mail: dev-help@maven.apache.org
Re: svn commit: r345273 - /maven/site/trunk/src/site/apt/guides/mini/guide-releasing.apt
Posted by Brett Porter <br...@apache.org>.
Jason van Zyl wrote:
> I've tried to relieve the tedium and try to provide more accurate and
> useful information for the history and easier linking of information. To
> that end there is now a little script here:
That's great - I'll try it out.
Can we agree on a template? I notice they you are doing a couple of
things that still get annoying for me:
- the horizontal lines which are not fun to type without the tool, and
which clutter the svn log command output which also uses horizontal
lines. I'm sure it will also look a bit much in the changelog report
- the URL: its easy enough to paste the issue in to the search box of an
already open jira window, and the URLs are likely to rot
(jira.werken.com -> jira.codehaus.org -> jira.wheredowegonext.org)
Remember, not everyone will be using the tool (eg, I mostly commit using
IDEA), and the current template has only the "PR:\nSubmitted by:" boiler
plate which is not much typing (and admittedly often there from the last
commit).
I thought we'd decided, and its documented here:
http://maven.apache.org/guides/development/guide-m2-development.html#Commit%20Message%20Template
I know I'm annoyingly picky about this, just humour me.
- Brett
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
For additional commands, e-mail: dev-help@maven.apache.org
Re: svn commit: r345273 -
/maven/site/trunk/src/site/apt/guides/mini/guide-releasing.apt
Posted by Jason van Zyl <ja...@maven.org>.
On Fri, 2005-11-18 at 10:59 +1100, Brett Porter wrote:
> Please use the template...
>
> I know its mostly in the commit, but I'd like to see issue # (not URL,
> as I'm not sure that triggers the subversion commits in JIRA), submitter
> and a summary so svn log/view history works.
I've tried to relieve the tedium and try to provide more accurate and
useful information for the history and easier linking of information. To
that end there is now a little script here:
http://svn.apache.org/viewcvs.cgi/maven/sandbox/issue/rissue/cm?
rev=345490&view=markup
You'll need the 'jira4r' library there as well.
Using Jesse's suggestion if you are in vi you can do:
:r ! cm MNG-100
And the issue information will pop up.
Not sure how Windows folks would do this but it was fun to do. Maybe
I'll whip off a python version for fun too :-)
> - Brett
>
> jvanzyl@apache.org wrote:
> > Author: jvanzyl
> > Date: Thu Nov 17 08:02:49 2005
> > New Revision: 345273
> >
> > URL: http://svn.apache.org/viewcvs?rev=345273&view=rev
> > Log:
> > o http://jira.codehaus.org/browse/MNG-1564
> >
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
> For additional commands, e-mail: dev-help@maven.apache.org
>
>
--
jvz.
Jason van Zyl
jason at maven.org
http://maven.apache.org
believe nothing, no matter where you read it,
or who has said it,
not even if i have said it,
unless it agrees with your own reason
and your own common sense.
-- Buddha
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
For additional commands, e-mail: dev-help@maven.apache.org
Re: svn commit: r345273 - /maven/site/trunk/src/site/apt/guides/mini/guide-releasing.apt
Posted by Brett Porter <br...@apache.org>.
Please use the template...
I know its mostly in the commit, but I'd like to see issue # (not URL,
as I'm not sure that triggers the subversion commits in JIRA), submitter
and a summary so svn log/view history works.
- Brett
jvanzyl@apache.org wrote:
> Author: jvanzyl
> Date: Thu Nov 17 08:02:49 2005
> New Revision: 345273
>
> URL: http://svn.apache.org/viewcvs?rev=345273&view=rev
> Log:
> o http://jira.codehaus.org/browse/MNG-1564
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
For additional commands, e-mail: dev-help@maven.apache.org