brett 2004/02/23 14:37:37
Modified: xdocs/reference/developers Tag: MAVEN-1_0-BRANCH
releasing-plugins.xml
Log:
update plugin release documentation
Revision Changes Path
No revision
No revision
1.4.4.1 +55 -58 maven/xdocs/reference/developers/releasing-plugins.xml
Index: releasing-plugins.xml
===================================================================
RCS file: /home/cvs/maven/xdocs/reference/developers/releasing-plugins.xml,v
retrieving revision 1.4
retrieving revision 1.4.4.1
diff -u -r1.4 -r1.4.4.1
--- releasing-plugins.xml 14 Oct 2003 01:19:36 -0000 1.4
+++ releasing-plugins.xml 23 Feb 2004 22:37:36 -0000 1.4.4.1
@@ -7,7 +7,7 @@
<section name="Changing a Plugin">
<p>
This page describes what Maven contributors or developers need to do when
- modifying a Maven plugin in Maven CVS:
+ modifying a Maven component or plugin in Maven CVS:
</p>
<ul>
<li>
@@ -17,14 +17,13 @@
or the format of the file.
</li>
<li>
- Update the <strong>xdocs/goals.xml</strong>,
- <strong>xdocs/properties.xml</strong> and other documentation files
- in <strong>xdocs/</strong>, reflecting your change.
- If the plugin has no xdocs, please generate skeletons using
+ Update the other documentation files in <strong>xdocs/</strong>, reflecting
your change.
+ For plugins, consider especially the <strong>xdocs/goals.xml</strong> and
+ <strong>xdocs/properties.xml</strong> files. If the plugin has no xdocs,
please generate skeletons using
<code>maven plugin:generate-docs</code>
</li>
<li>
- Ensure that the version in plugin.xml is a SNAPSHOT, e.g.
+ Ensure that the version in project.xml is a SNAPSHOT, e.g.
<strong><currentVersion>1.1-SNAPSHOT</currentVersion></strong>,
and <b>not</b>
<strong><currentVersion>1.1</currentVersion></strong>.
Unless you are in the process of creating a release of course.
@@ -38,77 +37,85 @@
<section name="Releasing Maven plugins">
<ul>
<li>
- <p>Modify the <code><currentVersion></code> in
<code>project.xml</code> to remove the
- <code>-SNAPSHOT</code> part
+ <p> Add a download link in the project navigation
(<code>navigation.xml</code>).
+ Example:
</p>
+ <source><![CDATA[
+<menu name="Downloads">
+ <item name="Eclipse Plugin 1.5"
+
href="http://www.ibiblio.org/maven/maven/plugins/maven-eclipse-plugin-1.5.jar"/>
+</menu>]]></source>
</li>
<li>
- <p>Modify the <code><versions>/<version></code> in
<code>project.xml</code>
- and ensure the correct id, name and expected tag.
+ <p> Create an <code>announcements</code> directory in the project and
inside create a
+ <code>[major].[minor].ann</code> text file containing the announce of the
release.
+ For an example, see
+ <a
href="http://cvs.apache.org/viewcvs.cgi/maven-plugins/scm/announcements/";>the SCM
plugin announcements</a>
</p>
</li>
<li>
- <p> Modify <code>changes.xml</code> to put the release date
+ <p>Modify the <code><currentVersion></code> in
<code>project.xml</code> to remove the
+ <code>-SNAPSHOT</code> part
</p>
</li>
<li>
- <p> Add a download link in the project navigation
(<code>navigation.xml</code>).
- Example:
+ <p>Modify the <code><versions>/<version></code> in
<code>project.xml</code>
+ and ensure the correct id, name and expected tag.
</p>
- <source>
- <menu name="Downloads">
- <item name="Eclipse Plugin 1.5"
href="http://www.ibiblio.org/maven/maven/plugins/maven-eclipse-plugin-1.5.jar"/>
- </menu>
- </source>
</li>
<li>
- <p> Create an <code>announcements</code> directory in the project and
inside create a
- <code>[major].[minor].ann</code> text file containing the announce of the
release.
- For an example, see
- <a
href="http://cvs.apache.org/viewcvs.cgi/maven/src/plugins-build/cactus/announcements/";>cactus</a>
+ <p> Modify <code>changes.xml</code> to put the release date
</p>
</li>
- <li>Commit your changes to CVS</li>
- <li>Produce a clean build of the plugin using <code>maven clean
plugin</code></li>
- <li>
+ <li><p>Commit your changes to CVS</p></li>
+ <li><p>
Tag the plugin project dir in CVS with
<code>MAVEN_[PROJECTNAME]_[MAJOR]_[MINOR]</code>
(for example <code>MAVEN_CACTUS_2_0</code>).
- </li>
- <li>
+ </p></li>
+ <li><p>Produce a clean build of the plugin using <code>maven clean
plugin</code></p></li>
+ <li><p>
Upload the new version to
<a
href="http://www.ibiblio.org/maven/maven/plugins/";>http://www.ibiblio.org/maven/maven/plugins/</a>
- using maven -DgroupId=maven -Dtype=plugin -Dartifact=/path/to/file
repository:copy-artifact
+ using</p><source><![CDATA[
+maven -DgroupId=maven -Dtype=plugin -Dartifact=/path/to/file
repository:copy-artifact]]></source>
</li>
<li>
<p> Send a quick release email to the Maven user list, using the content of
<code>[major].[minor].ann</code>.
</p>
</li>
- <li>
- <p> Increase the version in <code>project.xml</code> and don't forget to
- prepend <code>-SNAPSHOT</code>
- </p>
- </li>
- <li>
- <p> Update <code>project.xml</code> to add a new
<code><version></code>
- tag for <code>HEAD</code>
- </p>
- <p> <strong>Relax!</strong>' </p>
- </li>
</ul>
</section>
<section name="Some related FAQs">
<ul>
<li>
<p> Q: When would I do a release?</p>
- <p> A: At the moment, the plugins have the same
- lifecycle as Maven as a whole. Thus the plugins need to be released at
least
- before Maven is released. Otherwise, you would do a release when you are
performing
- a major change on a plugin that is breaking some compatibility and you want
to
- make the earlier version available to support existing users so that they
can
- still use the older version before they migrate to the new one.
+ <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
+ minor bugfixes.
+ </p>
+ </li>
+ <li>
+ <p> Q: What is the convention for versioning? </p>
+ <p> A: Rewrites and changes that break compatibility are a major version
number change.
+ 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>.
+ 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.
+ eg. <code>1.0.1</code> - use less whitespace in output HTML.
+ </p>
+ </li>
+ <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
+ 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>
- <p>In the future, plugins will have their own release lifecycle.</p>
</li>
<li>
<p> Q: Why would I want to given all the pain it will take?</p>
@@ -122,18 +129,8 @@
no choice :-) </p></li>
</ol>
</li>
- <li><p> Q: What is the advantage of releasing new version of a plugin if no
one is whining
- that the built version is broken?</p>
- <p> A: Ideally plugin changes should not break existing users. If the
changes are not
- breaking anything then sure, there is no point in doing a release. Waiting
for users
- to say it's broken is not a nice option, especially if you know you're
breaking
- the plugin. If you do, a better approach is to release the exsiting plugin
and bump
- the version number, so that at least existing users can keep the older
plugin.
- Not perfect, but will be good when plugins have their own lifecycle and
especially when
- users will be able to choose what plugin version to use in their
project.xml!
- </p>
- </li>
</ul>
</section>
</body>
-</document>
\ No newline at end of file
+</document>
+
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
