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.

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 classifiers javadoc and sources and assembles the names with artifactId and version with extension 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.extension

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.

Provide Files Checksums

All files deployed need to have valid checksum files (containing hex-encoded checksum value):

• .md5 and .sha1 are required,
• .sha256 and .sha512 are supported but not mandatory.

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.md5
example-application-1.4.7.pom.sha1
example-application-1.4.7.jar.md5
example-application-1.4.7.jar.sha1
example-application-1.4.7-sources.jar.md5
example-application-1.4.7-sources.jar.sha1
example-application-1.4.7-javadoc.jar.md5
example-application-1.4.7-javadoc.jar.sha1

and you can include the files

example-application-1.4.7.pom.sha256
example-application-1.4.7.pom.sha512
example-application-1.4.7.jar.sha256
example-application-1.4.7.jar.sha512
example-application-1.4.7-sources.jar.sha256
example-application-1.4.7-sources.jar.sha512
example-application-1.4.7-javadoc.jar.sha256
example-application-1.4.7-javadoc.jar.sha512

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.

Notice that .asc files don't need any additional checksum file, nor checksum files don't need .asc signature file.

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 name
• artifactId: the unique name for your component
• version: 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.

Note

While these elements are required, the URL itself does not need to be public. You can specify a URL inaccessible to the public or even a placeholder noting that your SCM URL is private and not meant for public access.

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

• https://github.com/simpligility/ossrh-demo/blob/master/pom.xml
• https://bitbucket.org/simpligility/ossrh-pipeline-demo/src