Introduction

The Maven POM format has been stable for several years. It is described by an XML schema (http://maven.apache.org/xsd/maven-4.0.0.xsd) that makes no allowance for extension. Thus, tools that read POMs are entitled to expect POMs to follow the schema precisely.

For Maven to add features and resolve long-standing problems, we need new information in POMs. To cite one example, the <scm/> element is groaning under the burden of comprehensive support for git. However, simply publishing a new schema is risky. Even if the new structure is entirely backward-compatible, existing tools may malfunction when presented with unexpected XML elements. It’s important to be very clear about this: even adding a new element to the POM with conventions that the old elements continue to contain the equivalent subset is unsafe. Informal XML parsers can malfunction when presented with new elements.

Hypothetically, the namespace rules of XML schema could permit POM extensions in other namespaces. However, this is no solution. For one thing, many XML parsers in the Maven ecosystem are not namespace-aware. For another, namespaces have problems of their own, and are not well-suited. It would be one thing if the POM had been designed around namespaces (c.f. Spring context XML files). But it was not.

Therefore, Maven needs a compatibility scheme that allows new versions to consume new POM formats, while leaving old versions, and other tools, consuming the old format(s). This document attempts to capture a design solution for this problem that has been discussed from time to time on the dev list.

Basic Design

The fundamental idea of this solution is to add a revision number to the artifact type of a POM. Right now, all POMs are of type ‘pom’. In this design, you can think of ‘pom’ as equivalent to ‘pom4’, and anticipate that the next step is to have new artifacts of type ‘pom5’.

On the surface, this seems simple and insufficient. Some new version of maven emits and consumes ‘pom5’ artifacts, and is thus completely disconnected from previous versions of Maven. That isn’t going to help anyone. Compatibility requires more complexity, as follows:
Down-conversion is required: It must be possible to derive a ‘pom4’ model from a ‘pom5’ model. While this process will inevitably lose information, the resulting ‘pom4’ model must at least permit a broad range of relatively ordinary projects to build.

• New Maven reads Old Pom: When looking for a POM in a repository, if the ‘pom5’ Maven fails to find a ‘pom5’, it must look for, and consume, a ‘pom4’.
• Publish old for new: Installing or Deploying a ‘pom5’ must, in parallel, install or deploy the corresponding ‘pom4’. Thus, ordinary deployment from the pom5 Maven produces an artifact consumable by old tools.

There has to be a way to refuse compatibility: The existing mechanism for specifying a minimal Maven version has to be clarified or extended. To the present reader, at least, it’s unclear to me whether the <prerequisites/> specification for the Maven version applies only to builds, or also to consuming the POM to resolve transitive dependencies and other artifact information. There should be a way to say, ‘I know that this POM is unsafe going backwards, don’t publish pom4’. We hope that this is used rarely, but we cannot anticipate all conditions. For extra credit, we could live up the the intention of the doc and extend this to specifying minimal versions of arbitrary plugins.

Do we need round-trip?

In theory, repository managers, at most, read ‘pom’ artifacts and treat unknown types as opaque. Thus, the design above should work without any initial changes to any repository manager. What if, however, some repository manager refused to cooperate in storing ‘pom5’ artifacts? I hope that this question is completely hypothetical. If it isn’t, we could consider some scheme of encoding ‘pom5’ data in special comments in ‘pom4’ files. This leads rapidly to a mare’s next, so I hope we don’t have to go there.