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="[EMAIL PROTECTED]">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 <[EMAIL
PROTECTED]></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 <[EMAIL PROTECTED]></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: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
