Changing a Plugin

This page describes what Maven contributors or developers need to do when modifying a Maven component or plugin in Maven CVS:

  • Update xdocs/changes.xml (create it if it does not exist) and describe the change, see the changes plugin or the format of the file.
  • Update the other documentation files in xdocs/, reflecting your change. For plugins, consider especially the xdocs/goals.xml and xdocs/properties.xml files. If the plugin has no xdocs, please generate skeletons using maven plugin:generate-docs
  • Ensure that the version in project.xml is a SNAPSHOT, e.g. <currentVersion>1.1-SNAPSHOT</currentVersion>, and <b>not</b> <currentVersion>1.1</currentVersion>. Unless you are in the process of creating a release of course.
  • Make sure the <version> section of project.xml is up to date. Create one if it is missing.

Releasing Maven plugins

  • Run maven scm:prepare-release and enter the appropriate tag (MAVEN_[PROJECTNAME]_[MAJOR]_[MINOR]) and version. This will update the currentVersion, versions entries, and xdocs/changes.xml file with the new version and release date. It will also commit your project.xml and xdocs/changes.xml files, then tag the resulting source tree.

    Note: This command will fail before doing any processing if there are modified files in your source tree other than project.xml and xdocs/changes.xml

  • Produce a clean build of the plugin using maven scm:perform-release. When prompted for the tag, enter the one used in the previous step. When prompted for the goal, enter plugin:repository-deploy,site:deploy.

  • Check for the new version at http://www.apache.org/dist/java-repository/maven/plugins/

  • Go the JIRA administration page for the Maven plugin you have just released (Note that you need to be a JIRA administrator for this project) and release the version. Also make sure to add a new version for the following development version. This is required so that issue creators/plugin developers can assign a "fix for" version to issues.

  • Run maven announcement. Edit this, then send it in a release email to the Maven user and developer lists.

Some related FAQs

  • Q: When would I do a release?

    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.

  • Q: What is the convention for versioning?

    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 1.13. 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. 1.0.1 - use less whitespace in output HTML.

  • Q: Who decides when a plugin can be released?

    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.

  • Q: Why would I want to given all the pain it will take?

    A: Several possible answers... :-) Pick yours.

    1. Because, making a release is honorific and you'll be thanked for it!

    2. 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.

    3. Because this is a rule all committers on Maven have agreed on, so you have no choice :-)