Java – Migrating to maven from an unusual svn directory structure

javamaven-2refactoringrelease-managementsvn

Contrary to a 'normal' svn directory structure I'm using the following structure:

trunk/
  project1/
  project2/
  project3/
  ...
branches/
  project1-branch/
    project1/
    project2/
    ...
  project2-branch/
    project1/
    project2/
    ...
tags/
  project1/
    V1
    V2
    ...

As you see I don't have separate triples (trunk/branches/tags) for each project.

For development I do a checkout of trunk (sometimes a sparse checkout) containing all the projects I need (there are dependencies between the projects and some projects are simply libraries).

The benefits that I see in this are:

Update and checkin is easy, because I have a common root directory (trunk) of all projects. One simple svn update or svn commit does it all.
Creation of a tag or branch is simple, because it's only the trunk that I have to svn copy for this.
(Branches and tags actually contain more projects than needed, but a svn copy is cheap and I still can do sparse checkouts on a branch or tag if needed.)
Moving of resources from one project to another is easy, because they all live in the same repository.
Global refactoring (for example changing the package of a commonly used class) is easy when I'm working on a full checkout of trunk, because I can be sure I don't miss a project.
Merging is easy, because I can always merge the whole branch at once even if there was a refactoring move from one project to another.

I intend to migrate to maven and split all the projects from trunk to maven projects. I'd like to benefit from the maven dependency management and from the available plugins (right now I'm using huge custom ant files).

Now my questions are:

Do I have to change the svn directory structure to give every project its own triple (trunk/branches/tags)? I guess the answer is 'yes'.
If I change the structure, which of the benefits mentioned above do I loose (I mean what will be more complicated doing it with maven)?
What are the equivalent ways to do it with maven?

Best Answer

There is no such thing, a "normal" svn directory structure. There are different approaches as discussed in the section called "Planning Your Repository Organization" of the Version Control with Subversion book (even the /trunk, /tags, /branches names are just conventions and there's no difference between a tag and a branch, except in your perception of them).

Do I have to change the svn directory structure to give every project its own triple (trunk/branches/tags)? I guess the answer is 'yes'.

No, you don't have to. See for example the Apache ServiceMix Source Tree: it's a multi modules maven project but the modules are under one trunk. On the other hand, XWiki which is not a single product but an ecosystem of products and projects as detailed in its Source Repository page, has many trunk/branches/tags. You can browse its repository here to get an idea of the layout.

But choosing one approach or the another is not just a matter of taste, it actually depends on your release cycle (more on mvn release later). If the components from your project share the same version (a la ServiceMix), I'd use only one trunk. If they have an independent release cycle (a la XWiki), I'd use a multiple "trunk/tags/branches" structure like the one described in this thread:

myrepo
  + .links (2)
    + trunks
      + pom.xml
  + parent-pom (1)
    + trunk
      + pom.xml
  + project-A
    + trunk
      + pom.xml
  + project-B
    + trunk
      + pom.xml 
1) The parent POM of the project has an own release cycle. Every component's POM will use it as parent (referenced simply with groupId and artifactId, no relativePath). For a release you'll have to release the parent POM first.

2) This is a construction to enable easy check outs of a specific branch of the project i.e. normally the trunk. A subversion user checks out myrepo/.links/trunk to get the head revision of all sources. The trick is, that that directory contains external links (i.e. with the svn:externals property) to the trunks of all other modules of this project (parent-pom, project-A, project-B). The pom.xml in this directory is never released, it contains simply a modules section for the three modules to enable a multi module build. With this construct you're able to setup easily branches e.g.:
myrepo
  + .links
    + branch-2.x
      + pom.xml

I've used this setup many times, it works quite well.

If I change the structure, which of the benefits mentioned above do I loose (I mean what will be more complicated doing it with maven)?

Let me answer each point one by one.

Update and checkin are easy thanks to svn externals. One simple svn update or svn commit does it all.
Creation of a tag or branch is simple because the maven release plugin will handle this for you (and tags and branches will be cleaner).
Moving of resources from one project to another doesn't look more complicated.
Global refactoring (for example changing the package of a commonly used class) is easy because you can still work on a full checkout of trunk.
Merging may be less easy. But do you really move classes from one project to another that frequently?

What are the equivalent ways to do it with maven?

Use the maven release plugin and one of the suggested layout with svn externals if required.

Problems of popular approaches

Most of the answers you'll find around the internet will suggest you to either install the dependency to your local repository or specify a "system" scope in the pom and distribute the dependency with the source of your project. But both of these solutions are actually flawed.

Why you shouldn't apply the "Install to Local Repo" approach

When you install a dependency to your local repository it remains there. Your distribution artifact will do fine as long as it has access to this repository. The problem is in most cases this repository will reside on your local machine, so there'll be no way to resolve this dependency on any other machine. Clearly making your artifact depend on a specific machine is not a way to handle things. Otherwise this dependency will have to be locally installed on every machine working with that project which is not any better.

Why you shouldn't apply the "System Scope" approach

The jars you depend on with the "System Scope" approach neither get installed to any repository or attached to your target packages. That's why your distribution package won't have a way to resolve that dependency when used. That I believe was the reason why the use of system scope even got deprecated. Anyway you don't want to rely on a deprecated feature.

The static in-project repository solution

After putting this in your pom:

<repository>
    <id>repo</id>
    <releases>
        <enabled>true</enabled>
        <checksumPolicy>ignore</checksumPolicy>
    </releases>
    <snapshots>
        <enabled>false</enabled>
    </snapshots>
    <url>file://${project.basedir}/repo</url>
</repository>

for each artifact with a group id of form x.y.z Maven will include the following location inside your project dir in its search for artifacts:

repo/
| - x/
|   | - y/
|   |   | - z/
|   |   |   | - ${artifactId}/
|   |   |   |   | - ${version}/
|   |   |   |   |   | - ${artifactId}-${version}.jar

To elaborate more on this you can read this blog post.

Use Maven to install to project repo

Instead of creating this structure by hand I recommend to use a Maven plugin to install your jars as artifacts. So, to install an artifact to an in-project repository under repo folder execute:

mvn install:install-file -DlocalRepositoryPath=repo -DcreateChecksum=true -Dpackaging=jar -Dfile=[your-jar] -DgroupId=[...] -DartifactId=[...] -Dversion=[...]

If you'll choose this approach you'll be able to simplify the repository declaration in pom to:

<repository>
    <id>repo</id>
    <url>file://${project.basedir}/repo</url>
</repository>

A helper script

Since executing installation command for each lib is kinda annoying and definitely error prone, I've created a utility script which automatically installs all the jars from a lib folder to a project repository, while automatically resolving all metadata (groupId, artifactId and etc.) from names of files. The script also prints out the dependencies xml for you to copy-paste in your pom.

Include the dependencies in your target package

When you'll have your in-project repository created you'll have solved a problem of distributing the dependencies of the project with its source, but since then your project's target artifact will depend on non-published jars, so when you'll install it to a repository it will have unresolvable dependencies.

To beat this problem I suggest to include these dependencies in your target package. This you can do with either the Assembly Plugin or better with the OneJar Plugin. The official documentaion on OneJar is easy to grasp.

Best Answer

Related Solutions

How to ignore a directory with SVN

Java – add jars to Maven 2 build classpath without installing them