Why do we have Requirements
Why Do We Have Requirements?⚓︎
In order to ensure a minimum level of quality of the components available in the Central Repository, we have established a number of requirements your deployment components have to meet. This allows your users to find all the relevant details about the components from the metadata provided in the Central Repository. The following sections will detail these requirements. n Helpful videos:
Requirements and Signing Tips
First Deployments
Project Object Model POM?!
Javadoc, Sources and Signing
Supply Javadoc and Sources⚓︎
Projects with packaging other than pom
have to supply JAR files that
contain Javadoc and sources. This allows the consumers of your components to
automatic access to javadoc and sources for browsing as well as for display and
navigation e.g. in their IDE.
The naming convention for these files following the Maven repository format
uses the classfiers javadoc
and sources
and assembles the names with artifactId
and version
with packaging jar
. E.g. with the values
<groupId>com.example.applications</groupId>
<artifactId>example-application</artifactId>
<version>1.4.7</version>
the files names for the javadoc and source archives using the pattern
artifactId-version-classifier.packaging
are
example-application-1.4.7-sources.jar
example-application-1.4.7-javadoc.jar
If, for some reason (for example, license issue or it's a Scala project), you
can not provide -sources.jar
or -javadoc.jar
, please make fake -sources.jar
or
-javadoc.jar
with simple README inside to pass the checking. We do not
want to disable the rules because some people tend to skip it if they have an
option and we want to keep the quality of the user experience as high as
possible.
Sign Files with GPG/PGP⚓︎
All files deployed need to be signed with GPG/PGP and a .asc
file containing the
signature must be included for each file. E.g. if you deploy the files
example-application-1.4.7.pom
example-application-1.4.7.jar
example-application-1.4.7-sources.jar
example-application-1.4.7-javadoc.jar
you need to include the files
example-application-1.4.7.pom.asc
example-application-1.4.7.jar.asc
example-application-1.4.7-sources.jar.asc
example-application-1.4.7-javadoc.jar.asc
If you need more help setting up and configuring GPG, please read our detailed instructions.
Sufficient Metadata⚓︎
As part of your deployment, you are required to submit a pom
file. This is the Project Object Model file used by Apache Maven to define your project and its build. When building with other tools you have to assemble it and ensure it contains the following information.
Besides the required information we strongly recommend to include the correct dependencies of your project, so that build tools can use that information to resolve transitive dependencies correctly and your users are not required to manually manage the dependencies.
Correct Coordinates⚓︎
The project coordinates, also known as GAV, coordinates determine the location of your project in the repository. The values are
groupId
: the top level namespace level for your project starting with the reverse domain nameartifactId
: the unique name for your componentversion
: the version string for your component
The version can be an arbitrary string and can not end in -SNAPSHOT
, since
this is the reserved string used to identify versions that are currently in
development. However we strongly suggest that you used [semantic versioning]
http://semver.org to assist your users in their version choice.
A valid example is
<groupId>com.example.applications</groupId>
<artifactId>example-application</artifactId>
<version>1.4.7</version>
In addition your project needs to include packaging
unless the default of jar
applies. Example packaging values are
jar
, war
,ear
, pom
, maven-plugin
, ejb
, rar
, par
, aar
and apklib
with other values being valid as well.
Project Name, Description and URL⚓︎
For some human readable information about your project and a pointer to your
project website for more, we require the presence of name
, description
and url
.
<name>Example Application</name>
<description>A application used as an example on how to set up pushing
its components to the Central Repository.</description>
<url>http://www.example.com/example-application</url>
A common and acceptable practice for name is to assemble it from the coordinates using Maven properties:
<name>${project.groupId}:${project.artifactId}</name>
License Information⚓︎
You need to declare the license(s) used for distributing your components. E.g. if you use the Apache License you can use
<licenses>
<license>
<name>The Apache License, Version 2.0</name>
<url>http://www.apache.org/licenses/LICENSE-2.0.txt</url>
</license>
</licenses>
Another example is the MIT license
<licenses>
<license>
<name>MIT License</name>
<url>http://www.opensource.org/licenses/mit-license.php</url>
</license>
</licenses>
Developer Information⚓︎
In order to be able to associate the project it is required to add a developers section.
<developers>
<developer>
<name>Manfred Moser</name>
<email>manfred@sonatype.com</email>
<organization>Sonatype</organization>
<organizationUrl>http://www.sonatype.com</organizationUrl>
</developer>
</developers>
It is acceptable to link to your profile on GitHub or other forges, if you do no have a website.
SCM Information⚓︎
The connection to your source control system is another required element. The
syntax used depends on the version control system used. connection
details
the read only connection, while developerConnection
details read and write
access connection details. The url
contains the URL for a web front end to your SCM system.
Detailed information is available in the Maven SCM documentation for various supported formats and a number of common examples follow.
Subversion on your own server:
<scm>
<connection>scm:svn:http://subversion.example.com/svn/project/trunk/</connection>
<developerConnection>scm:svn:https://subversion.example.com/svn/project/trunk/</developerConnection>
<url>http://subversion.example.com/svn/project/trunk/</url>
</scm>
Git hosted on GitHub:
<scm>
<connection>scm:git:git://github.com/simpligility/ossrh-demo.git</connection>
<developerConnection>scm:git:ssh://github.com:simpligility/ossrh-demo.git</developerConnection>
<url>http://github.com/simpligility/ossrh-demo/tree/master</url>
</scm>
Git hosted on BitBucket
<scm>
<connection>scm:git:git://bitbucket.org/simpligility/ossrh-pipeline-demo.git</connection>
<developerConnection>scm:git:ssh://bitbucket.org:simpligility/ossrh-pipeline-demo.git</developerConnection>
<url>https://bitbucket.org/simpligility/ossrh-pipeline-demo/src</url>
</scm>
Mercurial on BitBucket
<scm>
<connection>scm:hg:http://bitbucket.org/juven/hg-demo</connection>
<developerConnection>scm:hg:https://bitbucket.org/juven/hg-demo</developerConnection>
<url>http://bitbucket.org/juven/hg-demo</url>
</scm>
Git on Apache Git Server from Apache Maven
<scm>
<connection>scm:git:https://git-wip-us.apache.org/repos/asf/maven.git</connection>
<developerConnection>scm:git:https://git-wip-us.apache.org/repos/asf/maven.git</developerConnection>
<url>https://github.com/apache/maven/tree/${project.scm.tag}</url>
<tag>master</tag>
</scm>
A Complete Example POM⚓︎
The following complete example shows the XML header and required elements of project
and modelVersion
as well as example elements and content.
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
<modelVersion>4.0.0</modelVersion>
<groupId>com.simpligility.training</groupId>
<artifactId>ossrh-demo</artifactId>
<version>1.0</version>
<packaging>jar</packaging>
<name>ossrh-demo</name>
<description>A demo for deployment to the Central Repository via OSSRH</description>
<url>http://github.com/simpligility/ossrh-demo</url>
<licenses>
<license>
<name>The Apache Software License, Version 2.0</name>
<url>http://www.apache.org/licenses/LICENSE-2.0.txt</url>
</license>
</licenses>
<developers>
<developer>
<name>Manfred Moser</name>
<email>manfred@sonatype.com</email>
<organization>Sonatype</organization>
<organizationUrl>http://www.sonatype.com</organizationUrl>
</developer>
</developers>
<scm>
<connection>scm:git:git://github.com/simpligility/ossrh-demo.git</connection>
<developerConnection>scm:git:ssh://github.com:simpligility/ossrh-demo.git</developerConnection>
<url>http://github.com/simpligility/ossrh-demo/tree/master</url>
</scm>
...
</project>
These are the requirements for the pom
file. In addition we discourage the
usage of <repositories>
and <pluginRepositories>
and instead publish any
required components to the Central Repository. This applies for your own
components as well as for 3rd party artifacts.
Fully configured example projects including metadata as well as dependencies and Maven build configuration are, for example, available at