Maven POM management guidelines

MavenPomManagement.md

To keep the POMs (project object models) sane and maintainable, here's my suggestion of a few simple rules.
As with many other things in development - a bit more work for whoever does the changes that will save a lot of work to future maintainers.

• Define dependency versions in <dependencyManagement>.
• If there are multiple dependencies from one project, define the version in properties.
  • Version properties are named version.{artifactId}.
• If you exclude a transitive dependency, write a comment why.
• Group dependencies by their purpose and origin:
  • Test deps, platform deps (Dropwizard), In-house deps (CSL), project deps (that is, other modules of the same project).
• Don't clutter the pom.xml with explicitely stating the defaults, e.g. <packaging>jar</packaging> or <relativePath>../pom.xml</relativePath>.
• Use BOMs of other projects, they are very helpful when resolving dependency conflicts.
• Whenever adding a dependency that you googled up because you needed some class, ALWAYS write a comment which class it was and what advice you followed.
• For libraries implementing particular functionality, write a comment which functionality it was brought in for.
  • If you don't do it, getting rid of the dependency is harder when the feature is removed.
• Try to isolate large conditional build operations into a profile. Can be active by default.
• Learn about combine.children="append" combine.self="override" https://gist.github.com/573/b1cb50918438295183e64d503edfd74c
• Don't force users of the project to comment/uncomment anything to change the build. Create profiles instead. The previous bullet will help.
• Separate build units into project modules.
  • It's totally ok to create a .jar in one module and a Docker image for it in another, using the dependency:copy goal to transfer the intermediate stuff.
  • A good sign that you need to split is if you're running out of lifecycle phases to bind to.
• Use Failsafe plugin instead of Surefire if you need to start and stop some service around the tests. Surefire will leave them running if the tests fail.
• ALWAYS put the dependency to the lowest possible project module, even if that will mean adding it to several modules.
• You should build and deploy source jars for all modules of your project, and ideally, also Javadoc.