Release Process

Release Process

Prerequisites

  • XWiki releases use Maven2 and the Maven2 Release plugin
  • XWiki is modular and some modules are released separately as they have their own release cycle (see below for more details)
  • Start by verifying that the Continuous Integration build succeeds before starting any release. If not fix it first.
  • You need to have an account on maven.xwiki.org (this is the machine hosting XWiki's remote repository) and you'll need a key setup on your account there so that you can ssh to it without having to enter username or password.
  • You need to create a settings.xml file in the .m2/ directory in your user home with the following configuration in it (This server configuration is the one used by the release and deploy plugins to upload artifacts on the XWiki remote Maven repository):
<settings>
 <profiles>
    ...
 </profiles>
 <activeProfiles>
    ...
 </activeProfiles>
 <servers>
   <server>
     <id>maven.xwiki.org</id>
     <username>hudson</username>
     <privateKey>/Users/vmassol/.ssh/key.ssh2.private.openssh</privateKey>
     <filePermissions>664</filePermissions>
     <directoryPermissions>775</directoryPermissions>
   </server>
 </servers>
</settings>       
Replace with your username and the location of your priate key of course.
The profiles and activeProfiles settings are the one described on the Building page.

Pre-Release Steps

  • Create a branch from which you'll do the release. Use mvn release:branch for this
  • Check all pending JIRA issues one by one and with the community decide what to do for them (postpone to next release, postpone the release, split the issue in 2 since a part was already committed, etc).

Release Steps

  • Create the release plan, i.e. list the full dependency chain of modules to release.
  • For each module to release perform the following:
    • Resolve all SNAPSHOT dependencies. The Release plugin will not let you release the module if it has SNAPSHOT dependencies. So if that module is depending on some other XWiki module that has not been released, you'll need to release that module first.
    • cd to the directory of the module you wish to release and type mvn release:prepare -Pci (the ci profile is there to ensure the full build is executed as some build things are only activated when running on the CI server and need them to run when doing a release). Maven will ask questions about the version of the release, the tag name, etc. Maven (2.0.9 or 2.1 it's same) has trouble with svn 1.5 and more precisely on svn tag creation. See http://jira.codehaus.org/browse/SCM-406 for details.
    • Run mvn release:perform -Pci
    • For the Core Rendering API module, edit the Release Notes to add the API breakage. To do so:
      • before the release, edit the module's pom.xml and remove the exclusion, then run "mvn clirr:check". Then copy paste the result in the Release Notes.
      • after the release, update the CLIRR configuration to remove the exclusions and to set the comparison version.
It's a good practice to do a dry run before running mvn release:prepare. You can do that using mvn release:prepare -DdryRun=true.

Once all modules you wish to release have been released you'll need to perform other actions:

  • Upload all the files on ObjectWeb's forge (till we serve the files from our Maven repository)
  • Release the versions in JIRA
  • Update xwiki.org:
    • Write the release notes
    • For each item in the release notes, ensure that there's a corresponding documentation update or addition on xwiki.org
    • Update code.xwiki.org with the new downloads (for eg for plugins and applications)
    • Update the Download page with the new links to ObjectWeb
    • Write an announcement blog post on xwiki.org
    • Update the Javadoc page to link to the new javadoc
  • Send an announcement email on the XWiki mailing lists (devs and users)
  • Post a news announcement on https://forge.objectweb.org/
  • Updates sites about XWiki releases:
  • Update myxwiki.org with the new version. This is to test the stability of the release and find problems on a real farm.
  • Enjoy some rest and pray that nobody discovers a blocking bug... :)
  • Start improving the build so that next time all this is done in mere seconds and automatically...

Detailed Maven2 process for releasing XE

Do the releases in the order below. For each step ask yourself whether it's required to release a new version or if the previous released version can be used instead. You can use fisheye to check the commit log and see if there have been any changes affecting a module since the previous release.

  1. Top level POM
    • Directory: xwiki-platform/pom
    • Commands: mvn release:prepare -Pci followed by mvn release:perform -Pci.
  2. Tools Parent POM
    • Directory: xwiki-platform/xwiki-tools/
      1*. Commands: Manually set the version and the correct scm tags in the POM, commit, manually create the SVN tag and then run mvn clean deploy -N
    • Commands: mvn release:prepare -Pci -N -Darguments=-N (remove directories copied in the tag using subversion client) followed by mvn release:perform -Pci -N -Darguments=-N.
  3. Configuration Resources Tool
    • Directory: xwiki-platform/xwiki-tools/xwiki-configuration-resources
    • Commands: mvn release:prepare -Pci followed by mvn release:perform -Pci.
  4. Jetty Resources Tool
    • Directory: xwiki-platform/xwiki-tools/xwiki-jetty-resources
    • Commands: mvn release:prepare -Pci followed by mvn release:perform -Pci.
  5. Core
    • Directory: xwiki-platform/core
    • Commands: mvn release:prepare -Pci followed by mvn release:perform -Pci.
  6. Packager Tool
    • Directory: xwiki-platform/xwiki-tools/packager
    • Commands: mvn release:prepare -Pci followed by mvn release:perform -Pci.
  7. Plugins POM
    • Directory: xwiki-platform/xwiki-plugins/
      1*. Commands: Manually set the version and the correct scm tags in the POM, manually create the SVN tag and then run mvn clean deploy -N
    • Commands: mvn release:prepare -Pci -N -Darguments=-N (remove directories copied in the tag using subversion client) followed by mvn release:perform -Pci -N -Darguments=-N.
  8. Scheduler Plugin
    • Directory: xwiki-platform/xwiki-plugins/scheduler
    • Commands: mvn release:prepare -Pci followed by mvn release:perform -Pci.
  9. Lucene Plugin
    • Directory: xwiki-platform/xwiki-plugins/lucene
    • Commands: mvn release:prepare -Pci followed by mvn release:perform -Pci.
  10. Mail Sender Plugin
    • Directory: xwiki-platform/xwiki-plugins/mailsender
    • Commands: mvn release:prepare -Pci followed by mvn release:perform -Pci.
  11. WatchList Plugin
    • Directory: xwiki-platform/xwiki-plugins/watchlist
    • Commands: mvn release:prepare -Pci followed by mvn release:perform -Pci.
  12. JODA Time Plugin
    • Directory: xwiki-platform/xwiki-plugins/jodatime
    • Commands: mvn release:prepare -Pci followed by mvn release:perform -Pci.
  13. Applications Parent POM
    • Directory: xwiki-platform/xwiki-applications/
      1*. Commands: Manually set the version and the correct scm tags in the POM, commit, manually create the SVN tag and then run mvn clean deploy -N
    • Commands: mvn release:prepare -Pci -N -Darguments=-N (remove directories copied in the tag using subversion client) followed by mvn release:perform -Pci -N -Darguments=-N.
  14. Panels Application
    • Directory: xwiki-platform/xwiki-applications/panels
    • Commands: mvn release:prepare -Pci followed by mvn release:perform -Pci.
  15. Scheduler Application
    • Directory: xwiki-platform/xwiki-applications/scheduler
    • Commands: mvn release:prepare -Pci followed by mvn release:perform -Pci.
  16. Statistics Application
    • Directory: xwiki-platform/xwiki-applications/statistics
    • Commands: mvn release:prepare -Pci followed by mvn release:perform -Pci.
  17. Skins Parent POM
    • Directory: xwiki-platform/skins/
      1*. Commands: Manually set the version and the correct scm tags in the POM, commit, manually create the SVN tag and then run mvn clean deploy -N
    • Commands: mvn release:prepare -Pci -N -Darguments=-N (remove directories copied in the tag using subversion client) followed by mvn release:perform -Pci -N -Darguments=-N.
  18. Albatross Skin
    • Directory: xwiki-platform/skins/albatross
    • Commands: mvn release:prepare -Pci followed by mvn release:perform -Pci.
  19. Toucan Skin
    • Directory: xwiki-platform/skins/albatross
    • Commands: mvn release:prepare -Pci followed by mvn release:perform -Pci.
  20. Web
    • Directory: xwiki-platform/web
    • Commands: mvn release:prepare -Pci followed by mvn release:perform -Pci. The buildnumber plugin used in the build of the web module doesn't work with the French locale. You'll need to momentarily configure your locale to English to make it work.
  21. XE
    • Directory: xwiki-products/xwiki-enterprise
    • Commands: mvn release:prepare -Pci followed by mvn release:perform -Pci,hsqldb -Darguments=-Pci,hsqldb. Because not all the database-dependant modules are executed, the dependencies in database/\*/pom.xml and distribution/\*/pom.xml must be updated: the tag version in the new tagged directory, and the next SNAPSHOT version for the branch. To build the MS Windows installer, Launch4J is using a binary called Windres which requires that the environment is NOT set to use UTF-8.

Detailed Maven2 process for releasing XEM

Do the releases in the following order:

  1. Top level POM. See the instructions for XE above.
  2. Tools Modules. See the instructions for XE above.
  3. Plugins POM. See the instructions for XE above.
  4. Scheduler Plugin. See the instructions for XE above.
  5. Mail Sender Plugin. See the instructions for XE above.
  6. WatchList Plugin. See the instructions for XE above.
  7. Application Manager Plugin
    • Directory: xwiki-platform/xwiki-plugins/application-manager
    • Commands: mvn release:prepare -Pci followed by mvn release:perform -Pci.
  8. JODA Time Plugin. See the instructions for XE above.
  9. Applications POM. See the instructions for XE above.
  10. Scheduler Application. See the instructions for XE above.
  11. Application Manager Application
    • Directory: xwiki-platform/xwiki-applications/application-manager
    • Commands: mvn release:prepare -Pci followed by mvn release:perform -Pci.
  12. Wiki Manager Plugin
    • Directory: xwiki-platform/xwiki-plugins/wiki-manager
    • Commands: mvn release:prepare -Pci followed by mvn release:perform -Pci.
  13. Wiki Manager Application
    • Directory: xwiki-platform/xwiki-applications/wiki-manager
    • Commands: mvn release:prepare -Pci followed by mvn release:perform -Pci.
  14. Enterprise Manager Product
    • Directory: xwiki-products/xwiki-enterprise-manager
    • Commands: mvn release:prepare -Pci,mysql,derby,hsqldb,pgsql -Darguments=-Pmysql followed by mvn release:perform -Pmysql,ci -Darguments=-Pmysql. The buildnumber plugin used in the build of the web module doesn't work with the French locale. You'll need to momentarily configure your locale to English to make it work.

Detailed Maven2 process for releasing XEclipse

Due to some difficulties in integrating Eclipse PDE Builds and Maven, XEclipse uses a different release process:

  1. Set version numbers to release version in pom.xml and MANIFEST.MF files.
  2. Create SVN tag for the version to be released.
  3. Compile and deploy XEclipse plugin: mvn deploy -DeclipseInstall=${eclipseDir}
  4. Compile and deploy XEclipse standalone for each platform mvn deploy -DeclipseInstall=${eclipseDir} -DpdeBuildVersion=${pdeBuildVersion} -Pplatform where platform is linux, macx86, macppc, windows. In order to discover the value for ${pdeBuildVersion} look at the version of the org.eclipse.pde.build in ${eclipseDir}/plugins
  5. Perform release on Jira
  6. Upload the generated artifacts to the Objectweb Forge.
  7. Update wiki pages and download links.
  8. Post annoucements on mailing lists.
  9. Create blog post.
  10. Set version numbers in pom.xml and MANIFEST.MF files to next version-SNAPSHOT.

Tips and Troubleshooting

  • If you get an out of sync error from OW's SVN when you run mvn release:prepare you'll need to svn up and rerun release:prepare.
  • If Maven fails when you runt release:prepare run first mvn clean install.
  • The Maven release plugin stores some properties files to keep track of where it is in the release process. If you need to start over and clean those files you can run mvn release:clean
  • If you want to be sure, use -Pci on all maven commands. It's supposed to be triggered automatically by the release process but it's not been tested yet.
  • If Maven fails to upload an artifact to the XWiki remote repository, it's possible there's a problem of permissions in that repository. In that case you'll need to log on laam.xpertnet.biz, go in /home/maven/public_html/repository/* and fix the permission.
  • If you are running Mac OS X 10.5 and have errors while checking in files in SVN during the release process, you might want to read this thread. A workaround is to store your password in clear text in your subversion configuration files. 

Announcement Email Example

The XWiki development team is pleased to announce the release of XWiki Enterprise 1.2 RC 3.

Go grab it at http://www.xwiki.org/xwiki/bin/view/Main/Download

This is the third and hopefully last release candidate for the 1.2 version. It fixes several bugs, especially regading Oracle support. The final release is still planned for mid-January.

Changes from 1.2RC2:

    * XWIKI-1993: Database schema update issue when migrating from XE 1.1.2 to 1.2 RC2 on Oracle 10g
    * XWIKI-1995: Error inserting NULL values in NOT-NULL fields under Oracle for Version Comments/Authors
    * XWIKI-1975: Exception displayed in the log when upgrading from a previous 1.2 release to 1.2 RC2
    * XWIKI-1979: FileUploadPlugin should not call cleanFileList in endRendering
    * XWIKI-1981: UI issue when using the new rights managements UI with IE7
    * XWIKI-1946: Attachment renaming in the WYSIWYG Editor doesn't keep the file extension
    * XE-175: Show the "delete" button next to members in the group only when the group is edited

For more information see the Release notes at:
http://www.xwiki.org/xwiki/bin/view/Main/ReleaseNotesXWikiEnterprise12RC3

Thanks
-The XWiki dev team

Release Plan

Steps to construct the release plan:

  • Run the following on enterprise/ & platform/web and for both the version to release and the last released version:
    mvn dependency:tree -DoutputFile=releaseplan.txt
    find . -name releaseplan.txt | xargs sed -n  -e 's/.*org.xwiki.*/&/p' -e 's/.*com.xpn.*/&/p' | sed  -e 's/^[+-\|\\ ]*\(.*\)/\1/' | sort -u
  • Perform a diff and add the information to the release notes. For example: Release notes for XE 2.0
  • You must also check JIRA to see if any changes have been done and if non changes appear in JIRA perform a svn log to ensure nobody has forgotten to create a JIRA issue for a given commit
  • The information gathered will allow you to know which modules to release and will allow to build the release notes by asking jira for the changes between the versions found.
Tags:
Created by Jerome Velociter on 2007/03/05 08:43
Last modified by Vincent Massol on 2009/10/14 15:54
This wiki is licensed under a Creative Commons license
2.2.1.27354