We will discuss the migration process from maven2 to maven3. This article doesn’t answer all questions regarding that process, but can serve as a road map and example for you to implement your own migration strategy.

In case of small or simple maven2 project, it is my opinion that migration to maven3 is rather simple and straightforward.

Knowing how huge and complex maven2 architecture can be, you case might be very different. This article is intended rather for enterprise or big team doing migration, not for individual with small maven2 project.

For smaller project, migration might be a really quick and painless process. You can still read the article and it might help you to port your project. But you don’t need a secure but complex work-flow described here.

In this article is presumed, that your enterprise uses a tool infrastructure, and maven2 is a part of it. Assumption about your enterprise tools:

Tools or Env:

Maven 2
Maven 3 beta
any Linux

Also possible:

other OS

Preferred:

Git, Svn or any other current SCM
CI tool like TeamCity or Hudson
Maven repository manager like Archiva or Nexus

What to expect from maven3 migration

Maven3 is expected to be the next big step on Maven evolution. Generally maven2 projects are compatible with maven3. So, migrating to m3 will be:
relatively simple (rather clean up and fix then any real change);
rather fast. Days to month of work to get really big m2 project into m3 (with m1->m2 migration, it sometimes took years because of plugins etc. which were different in m2);
maybe requiring additional enterprise tools. If you still use legacy repositories of M1, you gonna need some Maven repository server like Nexus or Archiva to serve the jars. Maven3 cannot use legacy layout on its own;
requiring a maven expert to migrate. If you have m2 infrastructure you will likely need an expert. Maven infrastructure might be huge and complex, experience means a lot here.

Example project to convert to M3

One client of mine is a (very) big company. Much of code written in java and build chain is maven2 – based.

This maven2 architecture may be described as:

• very clean and professional;
• huge;
• module and reactor based;
• complex, uses all what maven2 has to offer and large number of plugins.

And now all this huge infrastructure is to be ported to maven3. Up until now we got our main code line working with maven3. Here is how.

1

Prepare

1.1

Migration strategy. All at once vs. small steps

Should all your main code line be taken or just one little test project?
I think it depends on how you answer following questions:

1) is your maven2 infrastructure clean, and professionally implemented and stable?
2) do you have a VERY good maven2 expert to do the migration?

If your answer is mostly ‘no’, start small and take time. If you mostly answer ‘yes’, than you have a good chance to get you projects m3 compatible rather fast.

1.2

How long will migration take

Basically it depends on size of your project. And of course on many parameters of your project I can’t know about. So, the following is just a very general assessment:

2 weeks to month: If you decided to go step by step (and answered mostly ‘no’ to the questions in previous chapter).
some days to week: In case you decided to convert your main code line at once (and answered rather ‘yes’ to the questions in previous chapter).

2

Migrate

2.1

Branch the current code line

Take the project or all code line you decided to migrate and branch the HEAD of it. It only makes sense to branch a HEAD which builds and can be considered m2 reference for your m3 build.

2.2

Only build in CI tool

We use TeamCity and Hudson. Your tool may be different. The point is: no local builds to prove that m3 works. It should work under CI, preferably distributed Ci to avoid any chance that it works for ’specific’ system only.

2.3

Install Maven3

There are two ways now: you can either install Maven3 on each system (agent, slave, whatever) you gonna build on, or you can add Maven3 directory to your test project (it will be available each time the CI tool makes checkout).

In first case (m3 per system) you will have on CI slave builder smth. like:

# ls /
/your/preferred/m3/path
..
/your/agent/root/checkout/workdir/p1/pom.xml
/your/agent/root/checkout/workdir/p2/pom.xml
..

and in second case (m3 in your branched project):

# ls /
..
/your/agent/root/checkout/workdir/m3/
/your/agent/root/checkout/workdir/p1/pom.xml
/your/agent/root/checkout/workdir/p2/pom.xml
..

I prefer the second case, because it means less trouble to begin with.

Download maven here: http://maven.apache.org/download.html

Just decompress and put it under /your/preferred/m3/path

2.4

Setup Maven3

The only thing you need is to ensure that m3 binary is first on the PATH.

Only for you Maven3 CI project, do smth. like:

export M3_HOME=/your/agent/root/checkout/workdir/m3/
export PATH=$M3_HOME/bin:$PATH

(How you achieve that depends on the tool you use)

2.5

Maven2 and Maven3 CI builds are ready

Now, you have m2 and m3 builds of exactly the same project. At least one, m2, must build. And if you are lucky, m3 does build as well.

3

Problems with m3 migration I know about

3.1

General

Here is a nice list of what can go wrong:
https://cwiki.apache.org/MAVEN/maven-3x-compatibility-notes.html

That it can go wrong, definitely doesn’t mean that it will. In my case, I had only 1 issue from this list: I had to get rid of all profiles.xml files.

Many real errors in some part of your code, plugin configurations and such, will fail under m3. That is because things which worked under m2 but were basically wrong will become obvious. We had some such cases but, once again, we have a very professional and experienced team and mature code.

3.2

Profiles.xml are removed

If you rely on even one profiles.xml, your build will fail.
What you need is to copy all between .. from profiles.xml to pom.xml.

Here is a basic tool I wrote to reintegrate you profile.xml into pom.xml.

It considers your project to be multi-module, so you give the top directory as a parameter. For structure like:

/your/workdir/project/module1/pom.xml
/your/workdir/project/module1/profiles.xml
/your/workdir/project/module2/pom.xml
/your/workdir/project/module2/profiles.xml
/your/workdir/project/module3/pom.xml
/your/workdir/project/module3/profiles.xml
..

you call java -jar maven3-import-profiles.jar -d /your/workdir/project

Here is the source…
Be prudent, don’t run the script if you have any risk of data loss. Good idea is to have an option to reset the project to previous state if something goes wrong. I used Git and git clean to remove local changes.

3.3

Strict check for duplicate dependencies

That is mentioned in the feature list of Maven3 and I found out that it fails m3 build in some cases (With maven3-polyglot build for example). But with current maven3 beta release it doesn’t seem to be an issue.

4

Time to stabilize Maven3 builds

Maven3 gives us unique opportunity of seamless translation from Maven2.
We already have seen how the migration of one particular project or code line can be implemented. After it is done you have two CI builds of the same project.
  The good idea is now to let m2 and m3 builds to run in parallel for some time. Maybe scheduled nightly builds. You now can compare test results, artifacts or any other type of build output to be the same.

There are several ways to implement continuous Maven3 builds from the current code line HEAD without actually changing it. Like: have maven3 and additional code in some separate branch and then use multiple checkout roots feature (Hudson and TeamCity definitely can do it). Or just re-base the branch each time HEAD gets an update.

To compare the build results, the same code line state for “m2 productive” and “m3 test” must be ensured.

You might encounter some features and problems to be fixed for Maven3, which were not obvious from the beginning.

After some time, then results are consistently equal, just retire the Maven2 build and make Maven3 productive.

5

Conclusion

Maven3 is still very new technology. And as such, there is much to learn about it, it brings bugs and new features. My experience porting rather big projects to the Beta version of Maven3 shows, that it can be already used in the production, and brings very new and much needed features with it. That is why after our builds are running stable under M3 for some time, we are going to migrate.

And how about you?