WicketStuff Core - Migration Guide

In November 2008 an initiative was started to organize the most used WicketStuff projects into a single tree that shared parent poms and a build and release cycle.  The goal was to make a more standard way of organizing WS projects and to make numbered releases of all of these projects that matched Wicket Core's release cycle.  For instance, when Wicket releases 1.4.0 final, our goal is to release the main WS projects as 1.4.0 final as well.

This effort is only focusing on the current WicketStuff trunk, targeting the 1.4-SNAPSHOT release.  When 1.4 final is released, this project will follow the example of Wicket and change trunk to point to the 1.5 release and create a branch dedicated to 1.4 development.

The wicketstuff-core folder was created in trunk to house all of the core projects that are participating in the unified release cycle.

If you would like to include your project in the wicketstuff-core, you need to do the following: (all of the following assumes you are working from a checked out version of WicketStuff trunk)

1. SVN MOVE - the first step is to move your project into the correct directory structure
   1. Note that we are getting rid of the "wicket-", "wicket-contrib-", and "wicketstuff-" prefixes for all projects that participate in the ws-core.  So, if you had wicket-contrib-yourproject, your svn command would be "svn move wicket-contrib-yourproject wicketstuff-core/yourproject". 
   2. PROJECTS WITH EXAMPLES (MULTI MODULE) - If you had "yourproject" and "yourproject-examples", we are consolidating those under a single parent.  Now you would issue the following commands to do this:
      1. mkdir wicketstuff-core/myproject-parent
      2. svn add wicketstuff-core/myproject-parent
      3. svn move wicket-contrib-myproject wicketstuff-core/myproject-parent/myproject
      4. svn move wicket-contrib-myproject-examples wicketstuff-core/myproject-parent/myproject-examples
      5. NOTE: naming is very important so that all maven plugins will work - especially the maven site plugin
   3. PROJECTS WITHOUT EXAMPLES - if you had just "wicket-yourproject", do the following:
      1. svn move wicket-yourproject wicketstuff-core/yourproject (notice, no "wicket-")
2. POM adjustments - now you need to make some adjustments in the POM file to reflect the new module hierarchy
   1. PROJECTS WITH EXAMPLES - if you had examples, you now have a folder named "yourproject" that contains the project itself and the examples as two subfolders.  The folder "yourproject" needs a new POM file.  Copy the example of the calendarviews POM (link), taking particular note of the following:
      1. The parent node - copy it exactly, with no changes.
      2. You should remove any declared groupId from this POM - your groupId must be org.wicketstuff (don't remove groupId from the parent node)
      3. Remove any declared version from the POM - version will be inherited from the parent (don't remove version from the parent node)
      4. Make your artifactId "yourproject-parent" and your packaging "pom"
      5. Make the "modules" node, and include "yourproject" and "yourproject-examples" as "module" nodes under it.  NOTE: The names MUST exactly match the directory names for the child directories or Maven will not handle it correctly, and it will limit our use of certain plugins.
   2. PROJECTS WITHOUT EXAMPLES - if you simply have one directory under wicketstuff-core that contains your project, make the following changes to your POM:
      1. add a "parent" node with the following three children:
         1. <groupId>org.wicketstuff</groupId>
         2. <artifactId>core-parent</artifactId>
         3. <version>1.4-SNAPSHOT</version>
         4. DO NOT include a relative path - it is not necessary since we follow naming conventions.  It will break certain plugins.
      2. Remove any groupId that you have declared for your project - it will inherit this from the parent.
      3. Remove any version that you have declared for your project - it will inherit this from the parent.
   3. ALL PROJECTS
      1. WICKET DEPENDENCIES
         1. All projects automatically inherit a dependency on the correct version of wicket.  Remove any dependency you have declared on Wicket from your POM files.
         2. If you depend on wicket-extensions, the version is declared as an optional dependency in the parent POM, so you need to remove the version from your POM files.  See the inmethod-grid as an example.
      2. SCM INFO
         1. Remove any SCM info from all of your POM files.  If you followed the naming conventions, the SCM info will be correctly inherited from the parent.
3. PARENT POM ADJUSTMENTS
   1. In the wicketstuff-core parent POM, add your project as a module under the modules node.  NOTE that the name added there must exactly match the directory name of your project.
4. VERIFY BUILD
   1. From the wicketstuff-core directory, run the command "mvn clean install".  Make sure everything builds successfully.
5. COMMIT YOUR WORK - something along the lines of:
   1. svn commit -m "woo hoo - i made the move" .
      

Send questions to the wicket users list (users@wicket.apache.org) with a subject similar to: "[WS REORG] - this is broken for me" (using a meaningful description of what's broken).