Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update and shorten central repository guide #645

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Update and shorten central repository guide #645

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
72 changes: 23 additions & 49 deletions content/apt/repository/guide-central-repository-upload.apt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,15 +29,14 @@

Guide to uploading artifacts to the Central Repository

In order for users of Maven to utilize artifacts produced by your project, you must deploy them to
a remote repository. Many open source projects want to allow users of their projects who build with
Maven to have transparent access to their project's artifacts. In order to allow for this, a project
should deploy their artifacts to the {{{/repository/}Central Repository}}.

In order for Maven users to depend on your project, you must deploy
both the artifact, the POM, and their PGP signatures to
a remote repository. The most common public shared repository is
{{{/repository/}Maven Central}}.

Requirements

[[1]] <<releases>>: Only <releases> can be uploaded to the Central Repository, that means files that won't change and that only depend on other files
[[1]] <<releases>>: Only <releases> can be uploaded to the Central Repository. That means files that won't change and that only depend on other files
already released and available in the repository,

[[2]] <<javadoc and sources>> for IDE lookup,
Expand All @@ -55,20 +54,6 @@ Requirements

The updated list of requirements can be found <<{{{https://central.sonatype.org/pages/requirements.html}here}}>>.

* Explanation

Some folks have asked <"why do we require all this information in the POM for deployed artifacts?">, so here's a small explanation.

The POM
being deployed with the artifact is part of the process to make transitive dependencies a reality in Maven. The logic for getting
transitive dependencies working is really not that hard, the problem is getting the data. The other applications
that are made possible by having all the POMs available for artifacts are vast, so by placing them into the Central Repository as part of the
process we open up the doors to new ideas that involve unified access to project POMs.

We ask for the license because it is possible that your project's license may change in the course of
its lifetime, and we are trying to create tools to help sort out licensing issues. For example, knowing all the licenses
for a particular graph of artifacts, we could have some strategies that would identify potential licensing problems.

* A basic sample:

+----+
Expand Down Expand Up @@ -116,22 +101,23 @@ Requirements

* PGP Signature

When people download artifacts from the Central Repository, they might want to verify these artifacts' PGP
When people download artifacts from the Central Repository, they should verify these artifacts' PGP
signatures against a public key server.
If there are no signatures, then users have no guarantee that they
are downloading the original artifact.

To improve the quality of the Central Repository, we require you to provide PGP signatures for all your artifacts (all
files except checksums), and distribute your public key to a key server like {{{http://pgp.mit.edu}http://pgp.mit.edu}}. Read
{{{http://central.sonatype.org/pages/working-with-pgp-signatures.html}Working with PGP Signatures}}
The Central Repository requires PGP signatures for all artifacts (all
files except checksums) with a public key available from a key server
like {{{https://pgp.mit.edu}https://pgp.mit.edu}}. Read
{{{https://central.sonatype.org/pages/working-with-pgp-signatures.html}Working with PGP Signatures}}
for more information.

* FAQ and common mistakes

* I have other <<<repositories>>> or <<<pluginRepositories>>> listed in my POM, is that a problem?
* I have other <<<repositories>>> or <<<pluginRepositories>>> listed in my POM. Is that a problem?

At present, this won't preclude your project from being included, but we do strongly encourage making sure all your dependencies
are included in the Central Repository. If you rely on sketchy repositories that have junk in them or disappear, it just creates havok for
are included in the Central Repository. If you rely on sketchy repositories that have junk in them or disappear, it creates havok for
downstream users. Try to keep your dependencies among reliable repos like Central, Jboss, etc.

* What about artifacts that can't be distributed because of their license?
Expand All @@ -141,10 +127,15 @@ Requirements

* I have a patched version of the foo project developed at foo.com, what <<<groupId>>> should I use?

When you patch / modify a third party project, that patched version becomes your project and therefore should be distributed under a <<<groupId>>> you control
as any project you would have developed, never under <<<com.foo>>>. See above considerations about <<<groupId>>>.
When you modify a third party project, that patched version becomes your project and therefore should
be only be publicly distributed under a <<<groupId>>> you control, never under <<<com.foo>>>.
(If you're only distributing to a private repository inside your organization, do whatevcer's convenient.)
When changing the group ID, you should also change the
Java package to avoid classpath conflicts and split package issues. See
{{{https://jlbp.dev/JLBP-6}JLBP 6}}.


* My project is hosted at a project hosting service like SourceForge or Github, what should I use as groupId?
* My project is hosted at a project hosting service like SourceForge or Github. What should I use as groupId?

If your project name is <<<foo>>> at SourceForge, you can use <<<net.sf.foo>>>.
If your username is <<<bar>>> on Github, you can use <<<com.github.bar>>>.
Expand All @@ -157,34 +148,17 @@ Publishing your artifacts to the Central Repository

* Approved Repository Hosting

Instead of maintaining repository rsync feeds for each projects, we now encourage projects to use an approved repository hosting location.
We encourage projects to use an approved repository hosting location.

Currently approved repository hosting locations:

* {{{https://repository.apache.org/}Apache Software Foundation}} (for all Apache projects)

* see {{{https://central.sonatype.org/publish/large-orgs/}the full list}}

[]

Automatic publication will be provided for Forges that provide hosting services for OSS projects and other large project repositories
that meet certain minimum criteria such as validation of PGP keys and pom contents as defined above. If you are interested in
becoming an approved Forge, {{{https://central.sonatype.org/publish/large-orgs/}contact us}}.

* Other Projects

The easiest way to upload another project is to use the
{{{https://central.sonatype.org/pages/ossrh-guide.html}Open Source Software Repository Hosting (OSSRH)}}, which is an approved repository provided
{{{https://central.sonatype.org/pages/ossrh-guide.html}Open Source Software Repository Hosting (OSSRH)}},
which is an approved repository provided
by Sonatype for <any> OSS Project that wants to get its artifacts into the Central Repository.

* Explanations

Having each project maintain its own repository with rsync to the Central Repository was the preferred process until January 2010.
However, we are no longer accepting rsync requests on a per project basis.

Over time, we have learned that this process is not scalable. Many of the projects being synced release very infrequently, yet
we have to hit hundreds of servers several times a day looking for artifacts that don't change. Additionally, there is no good
mechanism currently for validating the incoming data via the rsync, and this leads to bad metadata that affects everyone.

The aggregation of projects into larger feeds allows us to sync faster and more often, and ensuring these locations
perform sufficient checks increases the quality of metadata for everyone.
Loading