svn commit: r532037 - /maven/site/trunk/src/site/apt/guides/mini/guide-central-repository-upload.apt

[ca...@apache.org]

Author: carlos
Date: Tue Apr 24 11:33:47 2007
New Revision: 532037

URL: http://svn.apache.org/viewvc?view=rev&rev=532037
Log:
Put automatic sync config in a more prominent place and provide more info

Modified:
    maven/site/trunk/src/site/apt/guides/mini/guide-central-repository-upload.apt

Modified: maven/site/trunk/src/site/apt/guides/mini/guide-central-repository-upload.apt
URL: http://svn.apache.org/viewvc/maven/site/trunk/src/site/apt/guides/mini/guide-central-repository-upload.apt?view=diff&rev=532037&r1=532036&r2=532037
==============================================================================
--- maven/site/trunk/src/site/apt/guides/mini/guide-central-repository-upload.apt (original)
+++ maven/site/trunk/src/site/apt/guides/mini/guide-central-repository-upload.apt Tue Apr 24 11:33:47 2007
@@ -13,43 +13,13 @@
  Maven to have transparent access to their project's artifacts. In order to allow for this a project
  must have their artifacts deployed to the Central Repository.
 
-* Step 1: Create an upload bundle
-
- Use the repository plugin provided with the standard Maven distribution to create an upload bundle:
-
-+----+
-
- mvn repository:bundle-create
-
-+----+
-
- The bundle will be created in your <<<target>>> directory with the name:
- <<<${pom.artifactId}-${pom.currentVersion}-bundle.jar>>>
- 
- If you want to include a jar with java sources in your upload (recommended, unless your license doesn't
- allow sources to be redistributed) the command to run is:
-
-+----+
-
- mvn source:jar javadoc:jar repository:bundle-create
 
-+----+
-
- If you are not using maven as your build system but want something
- uploaded to the Central Repository then you just need to make a JAR (using the <<<jar>>> executable,
- not <<<zip>>>, <<<pkzip>>> or equivalent) with the following content:
+Requirements
 
-+----+
+ Only releases can be uploaded to the central repository, that means files that won't change and that only depend in other files
+ already released and available in the repository.
 
-pom.xml
-foo-1.0.jar (or whatever artifact is referred to in the pom.xml)
-foo-1.0-sources.jar (optional, jar containing java sources)
-foo-1.0-javadoc.jar (optional, jar containing javadocs)
-
-+----+
-
- Note that the bundle will be read by a script, so it must follow the above format. Also,
- the <<<pom.xml>>> must at least contain the following elements:
+ There are some requirements about the minimal information in the poms that are in the central repository. At least these must be present
 
  * modelVersion
 
@@ -73,12 +43,44 @@
 
  * dependencies
 
- []
 
- Be sure to always check previous versions of the poms in the repository to use the information
- already there as a base.
+ <<groupId>>: it will identify your project uniquely across all
+ projects, so we need to enforce a naming schema. For projects with artifacts already uploaded to the Central Repository it can
+ be equal to the one used previously, but for new projects it has to follow the package name rules, what
+ means that has to be at least as a domain name you control, and you can create as many subgroups
+ as you want.
+ There are a lot of poorly defined package names so you <<must provide proof that you control the domain>> that
+ matches the groupId. Provide proof means that the project is hosted at that domain or it's owned by a member,
+ in that case you must give the link to the registrar database (whois) where the owner is listed and the page
+ in the project web where the owner is associated with the project.
+ eg. If you use a com.sun.xyz package name we expect that the project is hosted at http://xyz.sun.com.
 
- A basic sample:
+ Look at {{{http://java.sun.com/docs/books/jls/third_edition/html/packages.html#7.7}
+ More information about package names}}. Check also the guide about
+ {{{guide-naming-conventions.html}Maven naming conventions}}
+
+ Examples:
+
+ * www.springframework.org -> org.springframework
+
+ * oness.sf.net -> net.sf.oness
+
+
+* 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 repository as part of the
+ process we open up the doors to new ideas that involve unified access to project POMs.
+
+ We also ask for license now because it is possible that your project's license may change in the course of
+ its life time and we are trying create tools to help normal people 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:
 
 +----+
 
@@ -113,28 +115,79 @@
 
 +----+
 
- []
 
- <<IMPORTANT>> considerations about the <<groupId>>: it will identify your project uniquely across all
- projects, so we need to enforce a naming schema. For projects with artifacts already uploaded to the Central Repository it can
- be equal to the one used previously, but for new projects it has to follow the package name rules, what
- means that has to be at least as a domain name you control, and you can create as many subgroups
- as you want.
- There are a lot of poorly defined package names so you <<must provide proof that you control the domain>> that
- matches the groupId. Provide proof means that the project is hosted at that domain or it's owned by a member,
- in that case you must give the link to the registrar database (whois) where the owner is listed and the page
- in the project web where the owner is associated with the project.
- eg. If you use a com.sun.xyz package name we expect that the project is hosted at http://xyz.sun.com.
 
- Look at {{{http://java.sun.com/docs/books/jls/third_edition/html/packages.html#7.7}
- More information about package names}}. Check also the guide about
- {{{guide-naming-conventions.html}Maven naming conventions}}
+Sync'ing your own repository to the central repository automatically
 
- Examples:
+ This is the preferred process. You first have to setup your project to
+ {{{http://maven.apache.org/plugins/maven-deploy-plugin/}deploy to a remote repository}}.
 
- * www.springframework.org -> org.springframework
+ You must make sure the remote repository server has rsync or rsync over ssh, there are free services like
+ {{{http://sf.net}Sourceforge}} that provide you {{{http://sourceforge.net/docman/display_doc.php?docid=4297&group_id=1#shell}ssh server access}}.
+
+ After you are able to deploy to your remote repository <<make sure you only deploy releases>>. Then you can provide a script like the
+ {{{http://svn.apache.org/viewvc/maven/archiva/trunk/maven-meeper/src/bin/synchronize/m2-sync/conf/}current scripts}},
+ open an issue under {{{http://jira.codehaus.org/browse/MAVENUPLOAD}MAVENUPLOAD}} and attach the script, and we'll add it to the automatically synced repos.
+
+ Make sure you provide proof of owning the domain that matches the groupId (see groupId considerations above). Proof means either the server to sync from has a name 
+ under that domain, your name shows up in a prominent place in the domain, or you provide a link to a whois database where your name shows up as the domain owner.
+
+ If you are using ssh in your own server you need to add the {{{http://www.ibiblio.org/maven/id_dsa.pub}maven public key}} to the authorized ones to allow us to log
+ in the machine.
+
+ Remember to subscribe to {{{mailto:repository-subscribe@maven.org}Maven repository mailing list}}.
+
+ <<Important>>: nothing is deleted or changed in the Central Repository after it is synced (except maven-metadata.xml files)
+
+
+
+Manual upload of artifacts
+
+ Note that this manual process is time consuming and <<will only be accepted for a limited number of requests>>. If you want to upload frequently read the
+ section above about automatic sync.
 
- * oness.sf.net -> net.sf.oness
+
+* Step 1: Create an upload bundle
+
+ Use the repository plugin provided with the standard Maven distribution to create an upload bundle:
+
++----+
+
+ mvn repository:bundle-create
+
++----+
+
+ The bundle will be created in your <<<target>>> directory with the name:
+ <<<${pom.artifactId}-${pom.currentVersion}-bundle.jar>>>
+ 
+ If you want to include a jar with java sources in your upload (recommended, unless your license doesn't
+ allow sources to be redistributed) the command to run is:
+
++----+
+
+ mvn source:jar javadoc:jar repository:bundle-create
+
++----+
+
+ If you are not using maven as your build system but want something
+ uploaded to the Central Repository then you just need to make a JAR (using the <<<jar>>> executable,
+ not <<<zip>>>, <<<pkzip>>> or equivalent) with the following content:
+
++----+
+
+pom.xml
+foo-1.0.jar (or whatever artifact is referred to in the pom.xml)
+foo-1.0-sources.jar (optional, jar containing java sources)
+foo-1.0-javadoc.jar (optional, jar containing javadocs)
+
++----+
+
+ Note that the bundle will be read by a script, so it must follow the above format.
+
+ []
+
+ Be sure to always check previous versions of the poms in the repository to use the information
+ already there as a base.
 
  []
 
@@ -167,20 +220,9 @@
 
 +----+
 
-* Explanation
 
- Some folks have asked why do we require the POM and license each time an artifact is deployed 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 repository as part of the
- process we open up the doors to new ideas that involve unified
- access to project POMs.
-
- We also ask for a license now because it is possible that your project's license may change in the course of
- its life time and we are trying create tools to help normal people 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.
 
-* Maven partners
+Maven partners
 
  The following sites sync automatically their project repository with the central one.
  If you want a project from any of these sites to be uploaded to the Central Repository you'll have to
@@ -195,19 +237,6 @@
  * {{{http://www.opensymphony.com/}OpenSymphony}}
 
  * {{{http://www.osjava.org}OS Java}}
-
-
-Sync'ing your own repository with ibiblio
-
- If you want to automatically sync your own repository to ibiblio you must make sure the server has rsync or rsync over ssh
- and provide a script like the
- {{{http://svn.apache.org/viewvc/maven/archiva/trunk/maven-meeper/src/bin/synchronize/m2-sync/conf/}current scripts}},
- open an issue under {{{http://jira.codehaus.org/browse/MAVENUPLOAD}MAVENUPLOAD}} with it and we'll add it to the automatically synced repos.
- If using ssh you need to add the {{{http://www.ibiblio.org/maven/id_dsa.pub}maven public key}} to the authorized ones to allow us to log in the machine.
-
- Remember to subscribe to {{{mailto:repository-subscribe@maven.org}Maven repository mailing list}}.
-
- <<Important>>: nothing is deleted or changed in the Central Repository after it is synced (except maven-metadata.xml files)
 
 
 For Maven developers