-
Notifications
You must be signed in to change notification settings - Fork 14
Identities
Projects are codebases with associated development effort and long-term lifetimes. Therefore, it's inappropriate to reference a particular project using a versioned coordinate. Projects may be referenced in this way perform high-level analyses such as project interdependency, quality metrics over the span of many releases, etc.
Projects are identified in Atlas using ProjectRef with a coordinate consisting of groupId:artifactId.
ProjectRefs are almost never appropriate in Maven. They can be used in plugin references (DEPRECATED), and that's about it. Maven allows specifying a plugin by groupId and artifactId, and it will resolve the version from the LATEST meta-version available in the repository. In practice, this is dangerous, since it can lead to unpredictable builds depending on the state of your local repository and which remote repositories you use. It can also lead to irreproducible builds, since the LATEST version for a plugin will change over time.
The whole point of a project is to release code for use in the wider world. When it does this, the release gets a particular version that fits into a broader context of releases for that project. For instance, releases should be sortable in terms of what came first vs. later. Their versions often also make certain claims about the quality of the release, such as alpha, beta, etc. However, it's important to note that a project release probably still references a set of artifacts.
In Maven, a project's release does have at least one dependable, concrete file associated with it: a POM. Often, if the Maven project isn't simply a parent POM, it will also have an implied, unclassified jar artifact associated with it as well, as the release's "main" artifact. This implied main-artifact jar is what allows most Maven dependency declarations get away with simply referencing the release of another project. If any other artifact from a project release is required, then a simple reference to the release is inappropriate.
Releases are identified in Atlas using ProjectVersionRef with a coordinate consisting of groupId:artifactId:version.
Common places to find ProjectVersionRef in Maven POMs are:
- Parent declaration (this is an implied ArtifactRef, with
type == pomandclassifier == null) - Plugin declaraion (this is an implied ArtifactRef, with
type == maven-pluginandclassifier == null) - Build extension declaration (this is an implied ArtifactRef, with
type == jarandclassifier == null) - Dependency declaration (ONLY when the main artifact is being referenced.) This is really an ArtifactRef that relies on default values
type == jarandclassifier == null. - Plugin-level dependency declaration (again, ONLY when the main artifact is being referenced.) This is really an ArtifactRef that relies on default values
type == jarandclassifier == null.
When a project performs a release, it produces something tangible that others can consume, either as a dependency in their own project (as a library), or directly (as an application). The products of a particular release are called artifacts, and normally correspond to actual files you can download from a Maven repository. Artifacts that vary from the main one for a project (normally a jar, war, etc.) are distinguished by their type and classifier. Classifier doesn't have to be specified when producing an extra artifact, and type defaults to jar. The main requirement for non-main artifacts is to avoid colliding with the main artifact, whose classifier is null and type is jar.
Technically speaking, dependency declarations in Maven use five coordinate parts: groupId, artifactId, version, type, and classifier. The reason most declarations can get by with a ProjectVersionRef (release coordinate) is because of the default values for type and classifier.
Artifacts are identified in Atlas using ArtifactRef with a coordinate consisting of groupId:artifactId:version:type[:classifier] where the default value of type is jar.
The only common places to find full-blown ArtifactRef's in Maven POMs are:
- Dependency declaration
- Plugin-level dependency declaration
Atlas also contains a javacc grammar for parsing versions. This is relatively stable for most mainstream version schemes, but some outliers may still cause problems.
The associated version-sorting implementation tries to follow the conventions described in: https://cwiki.apache.org/confluence/display/MAVENOLD/Versioning with a few notable exceptions. Wherever two schemes clash and are unlikely to co-exist for a single project, their direct comparison may differ from that described in the wiki. This was done for the sake of simplicity, and seems like a reasonable compromise for now.