Build Conventions
Description
Naming
Naming conventions are based on Maven's Guide to naming conventions on groupId, artifactId and version
When you create new module, there are entities that require consistent naming:
- Folder structure that leads to module location
- In pom.xml
- project.groupId
- project.artifactId
- project.name
- project.version
Leaf module folder name
- Only lower case English letters and "-" sign are allowed.
- Folder name must not duplicate information carried in the parent folders
- Folder name must be singular
project.groupId
Will identify your project uniquely across all projects, so we need to enforce a naming schema.
- It has to follow the package name rules (see More information about package names.)
- Package name must be singular
- Has to be at least as a domain name "org.xwiki" followed by corresponding module name.
- A good way to determine the granularity of the groupId is to use the project structure. That is, in a multiple module project, it should append a new identifier to the parent's groupId eg.
org.xwiki.plugin.archetype
org.xwiki.plugin.sample
project.artifactId
is the name of the jar without version
- Only lower case English letters and "-" sign are allowed.
- Must uniquely identify the artifact when resulting jars end-up in libraries (since artifact ID is the same as resulting jar name). So artifact id is constructed based on folder structure.
<project-name>-<top-level-module-name>-<sub-module-name>-...-<leaf-module-name>-<qualifier>
for XWiki project always <project-name>=xwiki. E.g. xwiki-plugin-archetype-parent
Based on type of the module output it might be appended with corresponding qualifier.
Suffix | Usage case |
---|---|
-parent | If this POM file is specified as "parent" in any other module |
-aggregator | If it's an aggregating project (builds several sub-projects). If module is both aggregator and parent then parent rule takes precedence. |
project.name
Name is a more literate view of atrifact ID and is helpful during project build to distinguish which module is currently built.
- Allows upper/lower case English letters, white-spaces and "-" sign.
- Words start with upper-case letter
- It's being constructed as
XWiki <top-level-module-name> - <sub-module-name> - ... - <leaf-module-name>
e.g. XWiki Plug-in - Sample - Publishing - News Harvester
Based on type of the module output it might be appended with corresponding suffix
Suffix | Usage case |
---|---|
- Parent POM | If this POM file is specified as "parent" in any other module |
- Aggregator | If it's an aggregating project (builds several sub-projects). If module is both aggregator and parent then parent rule takes precedence. |
project.version
project.description
While optional, still much recommended to add a good description to module general purpose and responsibilities.
Samples
Let's imagine some hypothetical plug-ins module, providing plug-in archetypes and several implementation samples. All implementations depend on parent plug-in archetype.
Table below illustrates the rules
Directory Structure | Group ID | Artifact ID | Name |
---|---|---|---|
plugin |-archetype | |-simple | |-reader | \-wizard |-dependency-installer |-plugins-parent-pom \-sample \-publishing |-custom-blog-processing \-news-harvester | org.xwiki.plugin org.xwiki.plugin.archetype org.xwiki.plugin.archetype org.xwiki.plugin.archetype org.xwiki.plugin.archetype org.xwiki.plugin org.xwiki.plugin org.xwiki.plugin.sample - org.xwiki.plugin.sample.publishing org.xwiki.plugin.sample.publishing | xwiki-plugin-aggregator xwiki-plugin-archetype-parent xwiki-plugin-archetype-simple xwiki-plugin-archetype-reader xwiki-plugin-archetype-wizard xwiki-plugin-dependency-installer xwiki-plugin-plugins-parent-pom xwiki-plugin-sample-aggregator - xwiki-plugin-sample-publishing-custom-blog-processing xwiki-plugin-sample-publishing-news-harvester | XWiki Plug-in - Aggregator XWiki Plug-in - Archetype - Parent POM XWiki Plug-in - Archetype - Simple XWiki Plug-in - Archetype - Reader XWiki Plug-in - Archetype - Wizard XWiki Plug-in - Dependency Installer XWiki Plug-in - Plugins Parent POM XWiki Plug-in - Sample - Aggregator - XWiki Plug-in - Sample - Publishing - Custom Blog Processing XWiki Plug-in - Sample - Publishing - News Harvester |