Migration from Maven2 to Maven3. Roadmap, example use case, what to expectBy neokrates, written on July 17, 2010
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.
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
✔ other OS
✔ 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;
- 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.
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.
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).
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.
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.
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
The only thing you need is to ensure that m3 binary is first on the
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)
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.
Problems with m3 migration I know about
Here is a nice list of what can go wrong:
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
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.
Profiles.xml are removed
If you rely on even one
profiles.xml, your build will fail.
What you need is to copy all between
Here is a basic tool I wrote to reintegrate you
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 ..
java -jar maven3-import-profiles.jar -d /your/workdir/project
💡 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.
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.
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.
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.
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?
LEARN MORE (amazon bookstore)