Redesign for more standards including Maven

Redesigning for more standards including Maven

NOTE: This is a work-in progress as of 1/28/2010

This is a proposed redesign of the layout in SVN and the way we use Maven, to enable broader use of standard tooling and approaches for development and release.

This redesign could be part of our move to a TLP (top level project), assuming we graduate .

Goals

Fix things that work poorly now.

• RAT reports - currently run on entire assembly, which means we have to unzip it, and run on that.
  • should run on pre-zipped things
  • Therefore, try to run on individual projects, not on distr

• Non Hierarchical POM layout (flat layout) causing problems
  • Release plugin doesn't work
    • may be fixed in latest version of Release Plugin
  • Assembly plugin "modules" doesn't work
  • m2eclipse works nicely with hierarchical layout
    • prototyped this already, and can make things work with hierarchical directory layout
  • Simple things like checking out all of uima - uimaj, uima-as, sandbox, (uimacpp - work on this later) from SVN with one export, and then being able to build, doesn't work
    • Current extract & build requires copying over / merging separate SVN checkouts

• Source release doesn't match SVN
  • should be just a zipped up version of the svn, or generated using the source mvn plugin.
  • source assembly should be (if possible) just the sources zipped up
    • may need to have a SVN structure that separates things not in releases (e.g. uimaj-internal-tools)

• Building from checkout - workspace and SVN layout don't match, so after checkout (via command line from a top level node like sandbox) you need to copy this into the same dir as another checkout (e.g., uimaj).
  • This was caused by earlier Eclipse needing to have everything in one level.
    • Now you can have the non-java projects imported into Eclipse, containing other java projects as subdirectories, and simultaneously, also import those Java projects into Eclipse as other projects
      • M2Eclipse does this, for example

• Many parts don't change from release to release - avoid re-releasing these
  • make more use of component part versions
  • support add-on projects being individually released

• POM hierarchy mixes up aggregation with inheritance
  • Follow new "best practice" of having at least some of the super POMs have integer version numbers, and not changing these very often (see TBD web ref)

• POMs used for overlapping purposes
  • Consider a superpom hierarchy that separates these separately, for easier maintenance
    • maven tooling dependency version
    • component dependency version (if appropriate)

• Make project versioning work with Release plugin
  • Substitute a more standard way for our use of "properties" for version numbers.
    • This should allow our POMs to have less version dependence.

• Balance maintenance-motivated DRY (don't repeat yourself) with obfuscation
  • sometimes having things factored so as to inherit from things and/or use properties set elsewhere in complex ways makes future readability / maintenance difficult.
  • using properties for version information in some cases is triggering warning messages, in m2eclipse, and in the next version of Maven (maven 3) - saying this is not good practice, and may not be supported in the future.

• Figure out Maven's approach to properties
  • It seems that there is a mechanism for "releases" that captures the settings of properties used in build the release, for reproducibility
  • It also seems there is a concept in the Release plugin where it substitutes actual values of properties when it makes the "tag", and then puts back the ${xxx} variable form when it updates the trunk. This allows the tagged item to be more "independent" of other components - for instance, when it is located in a Maven repository as a downloadable artifact.

Support future incorporation of Continuous Integration (CI)

Add Website support automation

Currently the website is maintained completely manually. More standards could enable automatic creation of various developer reports, updating the download page as part of the release process, etc.

Design

Principles:

• top level in svn tree:
  • uima - overall top
    • uimaj - java sdk for framework
    • uimacpp - cpp for framework
    • uima-as - uima addon for asynch scaleout
    • sandbox - for developing things, not all released, not necessarily well documented, etc.
    • site

• new top level things:
  • under uima
    • internal-tools - things not in normal binary distributions, but used in building, etc.
    • super-poms - non-aggregate poms in the super-pom hierarchy
    • annotators - released and more fully documented/supported annotators from the sandbox (called out because of importance)
    • add-ons - released and more fully documented/ supported add-ons, such as simple-server

Each of these (other than site) are "releasable" and have trunk/branch/tag nodes.

Some of these have individually releasable parts (e.g., each pom in super-poms, each annotator in annotators), while others are multi-module projects (like uimaj).

It should be possible (he said bravely) to do releases of parts individually, even when the trunk/tag/branch is at a higher level. For doing this, let's follow a convention, of naming the tag with a name-part starting with the releasable-part name.

• For example, with sandbox/trunk/projXyz the tag would be sandbox/tags/projXyz-version-number-etc
• To give a counter-example, what we're not doing is something like
  • (not doing) sandbox/projXyz/trunk
  • (not doing) sandbox/projXyz/tags/version-number-etc ...

• separate "aggregate" and "super" poms
  • for super poms - put in containing super-poms project
• scm element in pom needs to point to where this pom is, in the svn tree (to make releasing conventional)
• change relative links in pom structure to assume the layout that m2eclipse would create