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/03/02 08:07:54 UTC
svn commit: r155894 - in maven/maven-1/core/trunk/xdocs:
developers/making-releases.xml developers/releasing-plugins.xml
navigation.xml reference/scripting.xml using/bestpractices.xml
Author: brett
Date: Tue Mar 1 23:07:51 2005
New Revision: 155894
URL: http://svn.apache.org/viewcvs?view=rev&rev=155894
Log:
scripting
Added:
maven/maven-1/core/trunk/xdocs/developers/making-releases.xml
- copied, changed from r155893, maven/maven-1/core/trunk/xdocs/developers/releasing-plugins.xml
Removed:
maven/maven-1/core/trunk/xdocs/developers/releasing-plugins.xml
Modified:
maven/maven-1/core/trunk/xdocs/navigation.xml
maven/maven-1/core/trunk/xdocs/reference/scripting.xml
maven/maven-1/core/trunk/xdocs/using/bestpractices.xml
Copied: maven/maven-1/core/trunk/xdocs/developers/making-releases.xml (from r155893, maven/maven-1/core/trunk/xdocs/developers/releasing-plugins.xml)
URL: http://svn.apache.org/viewcvs/maven/maven-1/core/trunk/xdocs/developers/making-releases.xml?view=diff&rev=155894&p1=maven/maven-1/core/trunk/xdocs/developers/releasing-plugins.xml&r1=155893&p2=maven/maven-1/core/trunk/xdocs/developers/making-releases.xml&r2=155894
==============================================================================
--- maven/maven-1/core/trunk/xdocs/developers/releasing-plugins.xml (original)
+++ maven/maven-1/core/trunk/xdocs/developers/making-releases.xml Tue Mar 1 23:07:51 2005
@@ -22,96 +22,118 @@
<title>Releasing Plugins</title>
<author email="brett@apache.org">Brett Porter</author>
</properties>
-<!-- TODO: on releasing plugins - document should be about versioning and releasing, be a best practice?
- - this needs review currently.
- -->
<body>
- <section name="Changing a Plugin">
- <p>
- This page describes what a Maven contributor or developer needs to do when
- modifying a Maven component or plugin in Maven CVS:
- </p>
- <ul>
- <li>
- Update <code>xdocs/changes.xml</code> (create it if it does not exist)
- and describe the change, see
- <a href="http://maven.apache.org/reference/plugins/changes/">the changes plugin</a>
- for the format of the file.
- </li>
- <li>
- Update the other documentation files in <code>xdocs/</code>,
- reflecting your change. For plugins, consider especially the
- <code>xdocs/goals.xml</code> and
- <code>xdocs/properties.xml</code> files. If the plugin has no
- xdocs, please generate skeletons using
- <code>maven plugin:generate-docs</code>
- </li>
- <li>
- Ensure that the version in project.xml is a SNAPSHOT, e.g.
- <code><currentVersion>1.1-SNAPSHOT</currentVersion></code>,
- and <b>not</b> <code><currentVersion>1.1</currentVersion></code>.
- Unless you are in the process of creating a release of course.
- </li>
- <li>
- Make sure the <code><version></code> section of project.xml is
- up to date. Create one if it is missing.
- </li>
- </ul>
- </section>
- <section name="Releasing Maven plugins">
- <p>
- Prerequesites: you must define the following properties in <code>~/build.properties</code>. (Note: you may
- want to put these in <code>maven-plugins/plugin-parent/build.properties</code> instead if you need to define
+ <section name="Following Best Practices">
+ <p>
+ At Maven, we eat our own dog food! Please make sure you are familiar with the
+ <a href="../using/bestpractices.html">Best Practices</a> document and follow those techniques.
+ </p>
+ </section>
+ <section name="Releasing Maven or a Plugin">
+ <p>
+ Prerequesites: you must define the following properties in
+ <code>~/build.properties</code>. (Note: you may
+ want to put these in
+ <code>maven-plugins/plugin-parent/build.properties</code> instead if you need to define
them differently for other projects).
- </p>
- <ul>
- <li><code>maven.repo.apache.username</code> - your apache username</li>
- <li><code>maven.repo.apache.privatekey</code> - the filename of your SSH private key</li>
- <li><code>maven.repo.apache.passphrase</code> - the passphrase for your private key (<b>not</b> your Apache password)</li>
- <li><code>maven.announcement.mail.from</code> - Your name and email address, as subscribed to the users and
- developers mailing lists, e.g. <code>Brett Porter <brett@apache.org></code></li>
- <li><code>maven.announcement.mail.server</code> - The SMTP server to use for sending the announcement mail.</li>
- </ul>
- <p>Release process</p>
- <ul>
- <li>
- <p>Run <code>maven scm:prepare-release</code> and enter the appropriate tag
- (<code>MAVEN_[PROJECTNAME]_[MAJOR]_[MINOR]</code>) and version. This will update the
- <code>currentVersion</code>, <code>versions</code> entries, and <code>xdocs/changes.xml</code> file
- with the new version and release date. It will also commit your <code>project.xml</code> and
- <code>xdocs/changes.xml</code> files, then tag the resulting source tree.<br/>
- <b>Note:</b> This command will fail before doing any processing if there are modified files in your
- source tree other than <code>project.xml</code> and <code>xdocs/changes.xml</code>.
- </p>
- </li>
- <li><p>Produce a clean build of the plugin using <code>maven -Dmaven.repo.list=apache scm:perform-release</code>.
+ </p>
+ <ul>
+ <li>
+ <code>maven.repo.apache.username</code> - your apache username
+ </li>
+ <li>
+ <code>maven.repo.apache.privatekey</code> - the filename of your SSH private key
+ </li>
+ <li>
+ <code>maven.repo.apache.passphrase</code> - the passphrase for your private key (
+ <b>not</b> your Apache password)
+ </li>
+ <li>
+ <code>maven.announcement.mail.from</code> - Your name and email address, as subscribed to the users and
+ developers mailing lists, e.g.
+ <code>Brett Porter <brett@apache.org></code>
+ </li>
+ <li>
+ <code>maven.announcement.mail.server</code> - The SMTP server to use for sending the announcement mail.
+ </li>
+ </ul>
+ <p><b>Release process</b></p>
+ <p>
+ For more general notes on making a release, please see the <a href="../using/releasing.html">Releasing</a>
+ documentation in the User's Guide.
+ </p>
+ <ul>
+ <li>
+ <p>Run
+ <code>maven scm:prepare-release</code> and enter the appropriate tag
+ (
+ <code>MAVEN_[PROJECTNAME]_[MAJOR]_[MINOR]</code>) and version.
+ </p>
+ </li>
+ <li>
+ <p>Produce a clean build using
+ <code>maven -Dmaven.repo.list=apache scm:perform-release</code>.
When prompted for the tag, enter the one used in the previous step. When prompted for the goal, enter
- <code>plugin:repository-deploy,site:deploy</code>.
- </p></li>
- <li><p>
+ <code>plugin:repository-deploy,site:deploy</code> for plugins, or
+ <code>jar:deploy,site:deploy</code> for an
+ individual JAR. To release a Maven distribution, see below.
+ </p>
+ </li>
+ <li>
+ <p>
Check for the new version at
- <a href="http://www.apache.org/dist/java-repository/maven/plugins/">http://www.apache.org/dist/java-repository/maven/plugins/</a>.</p>
- </li>
- <li>
- <p>
- Go to the <a href="http://jira.codehaus.org/secure/project/ViewProjects.jspa">JIRA administration page</a>
- for the Maven plugin you have just released (Note that you need to be a JIRA administrator for this project) and
- <strong>release</strong> the version. Also make sure to <strong>add</strong> a new version for the following
- development version. This is required so that issue creators/plugin developers can assign a "fix for" version
+ <a href="http://www.apache.org/dist/java-repository/maven/plugins/">http://www.apache.org/dist/java-repository/maven/plugins/</a> or
+ <a href="http://www.apache.org/dist/java-repository/maven/jars/">http://www.apache.org/dist/java-repository/maven/jars/</a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Go to the
+ <a href="http://jira.codehaus.org/secure/project/ViewProjects.jspa">JIRA administration page</a>
+ for the Maven subproject you have just released (Note that you need to be a JIRA administrator for this project) and
+ <strong>release</strong> the version. Also make sure to
+ <strong>add</strong> a new version for the following
+ development version. This is required so that issue creators/developers can assign a "fix for" version
to issues.
- </p>
- </li>
- <li>
- <p>Run <code>maven announcement</code>. Edit this, then send it in a release email to the Maven user and developer lists. If you are happy with the default announcement, run <code>maven announcement:mail</code>.
- </p>
- </li>
- </ul>
- </section>
+ </p>
+ </li>
+ <li>
+ <p>Run
+ <code>maven announcement</code>. Edit this, then send it in a release email to the Maven user and
+ developer lists. If you are happy with the default announcement, run
+ <code>maven announcement:mail</code>.
+ </p>
+ </li>
+ </ul>
+ </section>
+ <section name="Releasing a Maven Distribution">
+ <p>
+ There are a couple of additional steps when releasing a Maven distribution.
+ </p>
+ <ul>
+ <li>Run
+ <code>maven maven:build-plugin-profile</code> and check the versions are what you expect to distribute
+ </li>
+ <li>Update the website files for the download links and release notes</li>
+ <li>Run
+ <code>scm:perform-release</code> with the goals
+ <code>jar:deploy,maven:installer</code>. Do this on Windows
+ so that the .exe file is generated
+ </li>
+ <li>Sign the distributions, and manually upload them to the distribution location (under
+ <code>/binaries/</code>
+ </li>
+ <li>Run
+ <code>scm:perform-release</code> with the
+ <code>site:deploy</code> goal, and mail out release notes
+ </li>
+ </ul>
+ </section>
<section name="Some related FAQs">
<ul>
<li>
<p> Q: When would I do a release?</p>
- <p> A: Plugins have their own release cycle now. So you can make a release whenever there is a
+ <p> A: Plugins have their own release cycle now. So you can make a release whenever there is a
change that you want to get into the hands of the users. This should be
for major bugfixes and thoroughly tested and complete new features.
You may also decide to make periodical releases every couple of months if there have only been
@@ -124,7 +146,8 @@
Announcements for these plugins should details what old functionality would be broken and
link to a migration document on the plugin project web site.
Minor version increments are for feature enhancements, major bugfixes and groups of bugfixes.
- These versions can go beyond 10: eg <code>1.13</code>.
+ These versions can go beyond 10: eg
+ <code>1.13</code>.
A third version increment is optional and signifies minor updates. These may also be deployed as
snapshots or users may just be asked to build out of CVS to acquire these fixes.
</p>
@@ -132,26 +155,13 @@
<li>
<p> Q: Who decides when a plugin can be released? </p>
<p> A: The lead developer of a plugin has the responsibility for making sure releases happen,
- but must first hold a vote on the Maven PMC list before cutting the release. The vote should detail
+ but must first hold a vote on the Maven Developer list before cutting the release. The vote should detail
the changes made and confirm that the testing has been performed and that there is no pending work
that should hold up the release.
</p>
</li>
- <li>
- <p> Q: Why would I want to, given all the pain it will take?</p>
- <p> A: Several possible answers... :-) Pick yours: </p>
- <ol>
- <li><p> Because, making a release is honorific and you'll be thanked for it! </p></li>
- <li><p> Because you have no choice. It is a rule in Maven land that we want to support
- our existing user base. This is something that we may not have done properly in the
- past and we need to tackle this issue now.</p></li>
- <li><p> Because this is a rule all committers on Maven have agreed on, so you have
- no choice :-) </p></li>
- </ol>
- </li>
</ul>
</section>
--->
- </body>
+</body>
</document>
Modified: maven/maven-1/core/trunk/xdocs/navigation.xml
URL: http://svn.apache.org/viewcvs/maven/maven-1/core/trunk/xdocs/navigation.xml?view=diff&r1=155893&r2=155894
==============================================================================
--- maven/maven-1/core/trunk/xdocs/navigation.xml (original)
+++ maven/maven-1/core/trunk/xdocs/navigation.xml Tue Mar 1 23:07:51 2005
@@ -105,19 +105,18 @@
<!-- TODO: Should references have an explanatory page? Eg summary about related projects, summary about subprojects -->
<menu name="Maven Subprojects">
<!-- TODO [later]: include PMC stuff -->
- <item name="About the Project" /><!-- href="/tlp/index.html" /> -->
+ <item name="About the Project" /><!-- href="/tlp/index.html" /> -->
<!-- TODO [later]: build sites -->
- <item name="Maven Wagon" /><!-- href="/wagon/index.html" /> -->
- <item name="Maven SCM" /><!-- href="/scm/index.html" /> -->
+ <item name="Maven Wagon" /><!-- href="/wagon/index.html" /> -->
+ <item name="Maven SCM" /><!-- href="/scm/index.html" /> -->
+ <item name="Continuum" /><!-- href="/continuum/index.html" /> -->
<item name="Components" collapse="true" href="/project/components.html">
- <item name="Maven Model Library" /><!-- href="/components/maven-model/index.html" /> -->
+ <item name="Maven Model Library" /><!-- href="/components/maven-model/index.html" /> -->
<item name="Maven Jelly Tags" href="/reference/maven-jelly-tags/index.html" />
</item>
</menu>
<menu name="Related Projects">
-<!-- TODO [later]: wait for a release -->
- <item name="Continuum" /><!-- href="http://continuum.codehaus.org/" /> -->
<item name="Mevenide" href="http://mevenide.codehaus.org/" />
<item name="Maven Proxy" href="http://maven-proxy.codehaus.org/" />
<item name="Ant" href="http://ant.apache.org/"/>
Modified: maven/maven-1/core/trunk/xdocs/reference/scripting.xml
URL: http://svn.apache.org/viewcvs/maven/maven-1/core/trunk/xdocs/reference/scripting.xml?view=diff&r1=155893&r2=155894
==============================================================================
--- maven/maven-1/core/trunk/xdocs/reference/scripting.xml (original)
+++ maven/maven-1/core/trunk/xdocs/reference/scripting.xml Tue Mar 1 23:07:51 2005
@@ -26,8 +26,27 @@
<body>
<section name="Scripting References">
- <!-- Explanatory note about how they are used -->
- <p>...</p>
+ <p>
+ Customised scripting in Maven is achieved in one of two ways:
+ </p>
+ <ul>
+ <li>Creating a <code>maven.xml</code> file containing custom goals</li>
+ <li>Creating your own plugin containing custom goals</li>
+ </ul>
+ <p>
+ Note that there are several <a href="../using/bestpractices.html#Scripting">best practices</a> related to
+ scripting that it is worth adhering to.
+ </p>
+ <p>
+ All scripts in Maven 1.x are written in the <a href="http://jakarta.apache.org/commons/jelly/">Jelly</a>
+ XML scripting language.
+ </p>
+ <p>
+ For an explanation of how to develop a plugin, please see <a href="../using/developing-plugins.html">Developing
+ Plugins</a>, or for details about <code>maven.xml</code> see the section on
+ <a href="../using/customising.html">Customising the Build</a>, both in the User's Guide.
+ </p>
+
<!-- TODO Maybe this is a single file, and belongs in using...
- ensure references to:
<item name="Ant" href="http://ant.apache.org/"/>
Modified: maven/maven-1/core/trunk/xdocs/using/bestpractices.xml
URL: http://svn.apache.org/viewcvs/maven/maven-1/core/trunk/xdocs/using/bestpractices.xml?view=diff&r1=155893&r2=155894
==============================================================================
--- maven/maven-1/core/trunk/xdocs/using/bestpractices.xml (original)
+++ maven/maven-1/core/trunk/xdocs/using/bestpractices.xml Tue Mar 1 23:07:51 2005
@@ -26,8 +26,73 @@
<body>
<section name="Best Practices">
- <!-- TODO: more to do -->
- <p>...</p>
+ <p>
+ One of the biggest advantages of Maven is that it makes things easiest when best practices are followed. There
+ are several recommended steps to take in setting up your build and developing the project that will help
+ detailed here.
+ </p>
+ <!-- TODO: more to come -->
+ <subsection name="Scripting">
+ <p>
+ Try to minimise the amount of scripting done. Those familiar with Ant will often put a lot of Ant tasks into
+ <code>maven.xml</code>. <i>You should try not to have a <code>maven.xml</code> file.</i>
+ </p>
+ <p>
+ The reason for this is that this starts to make each build behave differently, losing one of the benefits of
+ having a uniform environment. It also requires more maintenance and documentation.
+ </p>
+ <p>
+ Try to look for plugins that provide the functionality you are looking for, configure existing plugins, or
+ even make small rearrangements to your project if you are just looking to reproduce existing funcationlity in
+ a different way.
+ </p>
+ <p>
+ If you do have to do scripting, it is highly recommended to create a separate plugin project that provides
+ these services so that it does not need to be duplicated across projects and the changes are isolated.
+ </p>
+ <p>
+ Things that are often placed in <code>maven.xml</code> are shortcut names for commonly used goal combinations,
+ specification of the default goal, and pre/postGoal definitions to make small modifications to the behaviour
+ of an existing goal - for example to add a new source root before compilation.
+ </p>
+ </subsection>
+ <subsection name="Writing Plugins">
+ <p>
+ Writing plugins is the best way to extend Maven and continue to share it among other projects. However due to
+ its architecture there are some things that are not recommended.
+ </p>
+ <p>
+ Firstly, try not to use <code>pre/postGoal</code> definitions inside a plugin. This will bind that plugin to
+ another plugin causing side effects when the plugin is loaded, but different effects when it is not. A better
+ solution is to define the behaviour in a new goal, and then have the projects using the plugin define the
+ <code>pre/postGoal</code> to call the new goal.
+ </p>
+ <p>
+ Also, try not to call into other plugins using <code>attainGoal</code>. This makes your plugin susceptible to
+ changes in the other plugin. Often you won't have an option - however the recommended way for plugins to
+ expose their functionality is using Jelly Tag Libraries, or even better - shared Java code.
+ </p>
+ <p>
+ Use of <code>prereqs</code> is strongly preferred over <code>attainGoal</code> in any situation other than
+ inside <code>pre/postGoal</code> definitions. This ensures the best order can be determined and that goals
+ are only executed once.
+ </p>
+ </subsection>
+ <subsection name="Project Development Cycle">
+ <p>
+ Whenever you start making changes after a recent release, you should check the <code>currentVersion</code>
+ tag in <code>project.xml</code> and ensure that it is <code><i>nextVersion</i>-SNAPSHOT</code>.
+ </p>
+ <p>
+ By tagging the version as <code>-SNAPSHOT</code> it signifies it is not released (so won't accidentally
+ overwrite the official release), and has the advantage that when published, newer versions will be downloaded
+ if it changes.
+ </p>
+ <p>
+ Part of the release process is to set <code>currentVersion</code> to the actual version released.
+ For more information, set <a href="releasing.html">Making Releases</a>.
+ </p>
+ </subsection>
<subsection name="Keep the Site Documentation Updated">
<p>
The
@@ -62,21 +127,6 @@
<p>
<b>Note:</b> In the future, Maven should be able to integrate tightly with your issue tracking system to
reduce the need for this.
- </p>
- </subsection>
- <subsection name="Project Development Cycle">
- <p>
- Whenever you start making changes after a recent release, you should check the <code>currentVersion</code>
- tag in <code>project.xml</code> and ensure that it is <code><i>nextVersion</i>-SNAPSHOT</code>.
- </p>
- <p>
- By tagging the version as <code>-SNAPSHOT</code> it signifies it is not released (so won't accidentally
- overwrite the official release), and has the advantage that when published, newer versions will be downloaded
- if it changes.
- </p>
- <p>
- Part of the release process is to set <code>currentVersion</code> to the actual version released.
- For more information, set <a href="releasing.html">Making Releases</a>.
</p>
</subsection>
</section>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
For additional commands, e-mail: dev-help@maven.apache.org