grkvlt
commented
8 years ago So, at the risk of an enormous bikeshed-style digression...
Names and Contextual Metadata
The name of an object is important because it tells us what the purpose of the object is, and perhaps something about its functionality. However, names should not be confused with metadata, for example in a filename, /path/to/something.file only something is the name, the file extension and path/to directory are not intrinsic parts of the name. Generally, it is undesirable to repeat metadata in the name, so /path/to/path-to-something-file.file would be considered redundantly verbose. We view the file in a certain context, that of it's location in a filesystem, or as part of a URL, and this gives us extra information about the scope and purpose of the artifact.
Directory Structure as Metadata
In the case of the pom.xml file in a Maven project, the only sensible place for it is the root of a project, so no further identification is required. Similar considerations apply to Java source code, where the directory structure for package names is enforced by the compiler, so only the class name need be encoded into the file, as Class.java. And when compiled, the directory structure is still required, so the .class files need never stand alone, and again do not need more identifying information in their names.
However, there are occasions where the directory structure a file is located in cannot be taken for granted. This is usually the case when an artifact is designed to be copied to other locations, out of the control of the original author. In many projects there will be a utility library, or a text handling library, and in the context of the build process the project structure makes it clear where these libraries belong - the implicit metadata of parent or ownership is provided by the filesystem location. The myproject/utils directory is different to the otherstuff/utils directory, by virtue of being in another checked out project. The difficulty arises when building a redistributable artifact out of these projects. The simplest choice is to have both projects create their own utils.jar artifact, but it is obvious that these can then never coexist as library dependencies in some larger project. So, we must resort to duplicating some of the implicit metadata available as context when the projects are being built. Here, this is the parent directory name, which is the name of the project. This gives us a nicely namespaced set of artifacts, namely myproject-utils.jar and otherstuff-utils.jar.
Clocker Libraries
A similar problem occurs with Clocker artifacts. We have, currently, common, swarm and kubernetes projects, which are quite generic terms. These are used in various ways, most commonly as part of a URL used to identify a Java resource and as a Jar archive. When part of a URL we are provided with context that allows us to determine that classpath://io.brooklyn.clocker.common:common/ca.bom refers to the Clocker project's common library, and the scope for confusion is very low. On the other hand, the presence of common-2.0.0.jar does not inform the user about the libraries purpose or context in any way. Therefore, to prevent such confusion, this pull request modifies the atrifactId settings of the sub-project POM files to prepend clocker- in the same way as the clocker-parent project and, indeed, all of the Brooklyn libraries which are named brooklyn-core-0.9.0.jar and so on. The changing of the artifactId but not the folder-names allows disambiguation without too much repetition, as renaming the project folders also to clocker-swarm etc. is simply repeating the fixed context that they must always appear in as a consequence of being subdirectories in the brooklyncentral/clocker GitHub repository.
drigodwin
Updated changes leftover from #346 and #329