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.

For every <artifactId>-<version>.jar file, you must provide a corresponding <artifactId>-<version>-sources.jar and a <artifactId>-<version>-javadoc.jar. While we do not attempt to evaluate the javadoc contents or the source code itself, we suggest that you provide accurate sources and comprehensive documentation. This will assist your component's users to make effective use of your library.

If you cannot provide sources or documentation, we allow uploading placeholder .jar files in order to pass validation. We suggest that you include a README.md file in the .jar that directs the user to where they can get further information about your project.

Provide File 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 checksum files, nor do checksum files need .asc signature files.

Required POM 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 you include the correct dependencies of your project. Build tools can use that information to resolve transitive dependencies correctly and your users will not be required to manually manage the dependencies.

Correct Coordinates

The project coordinates, also known as GAV (group, artifact, version) 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 but cannot end in -SNAPSHOT, since this is the reserved string used to identify versions that are currently in development. However we strongly suggest that you use [semantic versioning] http://semver.org to assist your users in their version choices.

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 jar is used. 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

We require the presence of name , description and a url for more, human readable, information. For example:

<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

Developer information is also required:

 <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 not 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. We discourage the usage of <repositories> and <pluginRepositories>, 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 available at:

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