commons-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
Subject svn commit: r922315 - in /commons/proper/commons-site/src/site/xdoc: building-m1.xml building.xml
Date Fri, 12 Mar 2010 16:27:28 GMT
Author: niallp
Date: Fri Mar 12 16:27:27 2010
New Revision: 922315

Copy old Maven 1 "building" page and start to update for Maven 2

      - copied, changed from r922219, commons/proper/commons-site/src/site/xdoc/building.xml

Copied: commons/proper/commons-site/src/site/xdoc/building-m1.xml (from r922219, commons/proper/commons-site/src/site/xdoc/building.xml)
--- commons/proper/commons-site/src/site/xdoc/building.xml (original)
+++ commons/proper/commons-site/src/site/xdoc/building-m1.xml Fri Mar 12 16:27:27 2010
@@ -44,9 +44,8 @@
     Some knowledge of maven is assumed in this document.  Please refer to the
     <a href="">maven user guide</a>
     <a href="">reference</a>
-    for more information. Most commons components now use version 1 of maven,
-    so this is the maven version assumed throughout this document. Updates
-    covering maven 2 are welcome!
+    for more information. This document is concerned with using version 1 of maven.
+    See <a href="building.html">here</a> for Maven 2 details.

Modified: commons/proper/commons-site/src/site/xdoc/building.xml
--- commons/proper/commons-site/src/site/xdoc/building.xml (original)
+++ commons/proper/commons-site/src/site/xdoc/building.xml Fri Mar 12 16:27:27 2010
@@ -37,47 +37,27 @@
     The assumption throughout is that we are working with a component named
     "Apache Commons Foo" that uses maven as its build system, both for
-    distribution binaries and for the web site.  Contributions of instructions
-    covering ant-based builds are welcome! 
+    distribution binaries and for the web site.
     Some knowledge of maven is assumed in this document.  Please refer to the
-    <a href="">maven user guide</a>
-    <a href="">reference</a>
-    for more information. Most commons components now use version 1 of maven,
-    so this is the maven version assumed throughout this document. Updates
-    covering maven 2 are welcome!
+    <a href="">maven user guide</a>
+    for more information. Most commons components now use version 2 of maven,
+    so this is the maven version assumed throughout this document.
+    See <a href="building-m1.html">here</a> for Maven 1 details.
   <section name='Local environment setup'>
     To build Apache Commons components or web sites, you need to have maven
-    installed and the project source files checked out locally. You may also
-    need to have some local build properties specified.  This section describes
-    the local setup required. 
+    installed and the project source files checked out locally.
     <subsection name='Getting and installing maven'>
       Follow the 
-      <a href="">
-      maven download instructions</a> to download and install maven. You will
-      need Maven version 1.0.2.
-      </p>
-      <p>
-      You need the maven-xdoc-plugin version 1.9.2 to build a Apache Commons
-      web site. If you don't have that version, you need to upgrade. To
-      automatically install the plugin, type the following on a single line:
-      <source>
-      maven plugin:download
-        -Dmaven.repo.remote=
-        -DgroupId=maven
-        -DartifactId=maven-xdoc-plugin
-        -Dversion=1.9.2
-      </source>
-      For a manual installation, you can download the plugin here:
-      <a href="">
+      <a href="">
+      maven download instructions</a> to download and install maven.
     <subsection name='Checking out the commons sources'>
@@ -94,256 +74,58 @@
     <subsection name='Configuring local properties'>
-      As a general rule, dependencies on local properties (things not specified
-      in <code>project.xml</code> or <code></code>)
should be
-      avoided. There are a few things, however, that are specific to individual
-      developers that may need to be set locally. Generally, only committers
-      need to set local properties.  As documented in the
-      <a href="">
-      maven properties reference</a>, maven looks for property values first in
-      <code></code> in the project's base directory (where
-      <code>project.xml</code> lives), then in <code></code>
-      that exists in the same directory, then in ${user.home}/
-      and finally in System properties. Values are successively overridden if
-      they occur in multiple places in this list.
-      </p>
-      <p>
-      It may be convenient for committers to set the
-      following properties in ${user.home}/, which will make
-      them apply to all maven projects that they work on.
-      <pre>
-      maven.username (apache user name, for site deployment)
-      maven.repo.apache.releases.username   (apache user name, for releases)
-      maven.repo.apache.releases.privatekey (path to pgp signing key)
-      </pre>
-      If you work only on Commons projects, you can add
-      <code> </code>
-      otherwise this will need to be specified for each project that you want
-      to use maven to deploy.
+      You only need to configure local properties if you want to build using
+      different versions of Java.
+      See <a href="commons-parent-pom.html#Testing_with_different_Java_versions">here</a>
+      for more details.
-  <section name='Maven POM (project.xml) configuration'>
-  <p>
-  This section describes the key elements in the maven POM and how the 
-  <a href="">
-  sample <code>project.xml</code></a> file needs to be modified or customized
-  for different components.
-  </p> 
-    <subsection name='Top level elements'>
+  <section name="Maven Commands">
+    <subsection name="Running the Tests">
-      The following top-level elements of the POM should be changed to reflect
-      the individual component.  Elements not listed below should keep the
-      values in the sample file.
-      <table><tr><th>Element</th><th>Value</th><th>Example
-      (value to replace)</th></tr>
-      <tr><td>name</td><td>The capitalized name of the component</td>
-      <td>Foo</td></tr>
-      <tr><td>groupId</td><td>commons-component (where "component"
is the
-      uncapitalized name of the component)</td><td>commons-foo</td></tr>
-      <tr><td>artifactId</td><td>commons-component (where "component"
is the
-      uncapitalized name of the component)</td><td>commons-foo</td></tr>
-      <tr><td>currentVersion</td><td>Current version under development.
-      Development versions should always use the suffix "-SNAPSHOT".
-      Maven handles these SNAPSHOTs in a special way.</td>
-      <td>1.0-SNAPSHOT</td></tr>
-      <tr><td>inceptionYear</td><td>Year when the component was created</td>
-      <td>2005</td></tr>
-      <tr><td>shortDescription</td><td>Apache Commons &lt;capitalized
-      </td><td>Apache Commons Foo</td></tr>
-      <tr><td>description</td><td><strong>Brief</strong>
description of what
-      the component is</td><td>A Foo thing</td></tr>
-      <tr><td>logo</td><td>Path to component logo image</td>
-      <td>/images/logo.png</td></tr>    
-      </table>
+        To run a component's tests:
-    </subsection>
-    <subsection name='Addtional POM elements'>
+      <source>mvn test</source>
+    </subsection> 
+    <subsection name="Creating a jar file">
-      In addition to the basic project information in the preceeding section,
-      the following POM elements need to be customized or at least verified for
-      individual commons components.
-      <table><tr><th>Element</th><th>Comments</th></tr>
-      <tr><td>versions</td><td>This list should include an entry
for each
-      official release of the component.  The <code>id</code> and 
-      <code>name</code> for each version should be the release number, e.g.,
-      "1.2".  The <code>tag</code> should be the name of the svn tag
-      corresponding to the sources used to build the release.</td></tr>
-      <tr><td>developers</td><td>This list should include all committers
-      work on the component. Each committer's first commit to the component
-      should include adding him/herself to the developers list.</td></tr>
-      <tr><td>contributors</td><td>Most commons components have done
away with
-      @author tags, so the way we acknowledge contributors is by adding them to
-      this list, which will appear on the maven-generated web site. Make sure
-      that you have the correct spelling of contributors' names and do not
-      include email addresses unless contributors specifically authorize this.
-      </td></tr>
-      <tr><td>dependencies</td><td>Minimize these ;-) and group them
-      comments designating them as compile-time, run-time and test-only if
-      these distinctions apply.</td></tr>
-      <tr><td>build</td><td>The sample file assumes the standard
-      layout, with source code in <code>src/jave</code> and tests in 
-      <code>src/test</code>. It also assumes that test classes have names that
-      end in "Test", e.g. "" and that abstract test classes
-      have names that end in "AbstractTest", e.g., "FooFooerAbstractTest." Do
-      <strong>not</strong> remove the <code>resources</code> element
-      includes <code>NOTICE.TXT</code>.</td></tr>
-      <tr><td>reports</td><td>Reports published to the live web site
should be
-      limited to the short list in the sample POM.  The 
-      <code>maven-changes-plugin</code> should only be used if the component
-      maintains a <code>changes.xml</code> file in <code>/xdocs</code>

-      following the format described in the
-      <a href="">
-      maven changes plugin documentation</a></td></tr></table>
+        To create a component's jar:
-    </subsection>
-  </section>
-  <section name='Property configuration'>
-    <p>
-    There is very little that needs to be customized for individual components
-    in the
-    <a href="">
-    sample <code></code> file</a>. The table below calls
-    a few properties which individual components may wish to modify.  The
-    deployment and site generation properties (which should not be changed) are
-    discussed in other sections below.
-    <table><tr><th>Property</th><th>Comments</th></tr>
-    <tr><td>maven.test.skip</td><td>Set to <code>true</code>
to skip unit tests
-    during build. Useful when testing build changes, but should not be checked
-    in with value set to <code>true.</code></td></tr>
-    <tr><td>maven.test.failure</td><td>Set this to <code>false</code>
to allow
-    the build to succeed when unit tests fail. This should not be checked in
-    with the value set to <code>false.</code></td></tr>
-    <tr><td></td><td>If the component
uses the
-    checkstyle plugin, this property should be set to the location of the
-    checkstyle rules file.</td></tr>
-    <tr><td>maven.javadoc.links</td><td>Components should add links
to any
-    javadoc resources beyond the jdk here.</td></tr></table>
-    </p>
-  </section>
-  <section name='Generating and publishing the web site'>
-    <subsection name='Generating the site'>
-    <p>
-    Use <code>maven site:generate</code> to generate the component web site
-    locally. Then review the generated html in <code>target/docs.</code>
-    Navigation is specified in <code>xdocs/navigation.xml.</code> The
-    <a href="">
-    sample navigation file</a> refers to entities defined in 
-    <code>../../commons-build/menus/menus.dtd,</code> so, as mentioned above,
-    commons-build has to be checked out as a peer to the component whose web
-    site you are building. The menu structure in the sample is standard for
-    commons components, though some elements (e.g, User's Guide) may not be
-    present for all components.  At the very least, each component
-    <strong>must</strong> include a link to the javadoc for the most recent
-    release.  Links to Javadoc for the last release and for the current
-    development branch should also be included.
-    </p>
-    </subsection>
-    <subsection name='Updating the public site'>
-    <p>
-    Once you have successfully generated the web site, reviewed it
-    locally and checked in any xdocs or configuration changes, you can deploy
-    it using <code>maven site:sshdeploy.</code>  For this to work, the 
-    following conditions need to be satisfied: <ol>
-    <li> The <code>&lt;siteAddress&gt;</code> and 
-    <code>&lt;siteDirectory&gt;</code> POM elements have to have the
-    <code></code> and 
-    <code>/www/</code> respectively (will be the
-    case if you do not change the settings in <code>project.xml.sample.</code>)
-    </li>
-    <li> You have to be a member of the <code>commons</code> unix group

-    (should happen when you are set up as a commons committer).</li>
-    <li> You have an ssh key set up. Follow the instructions on the
-    <a href="">
-    apache SSH Access page</a> to get this set up correctly.</li></ol>
-    Assuming the second condition above is met, you can also deploy sites
-    manually using scp or by tarring / zipping and extracting the content
-    to the path above on <code></code>  In either case,
-    The content will be rsynced within a few hours to the production
-    web server(s).  Note that because of the rsync delay, 
-    <strong>your changes will not appear immediately on the live site.</strong>
-    </p>
-    </subsection>     
-  </section>
+      <source>mvn package</source>
+    </subsection> 
-  <section name='Deploying jars'>
-    <p>
-    Maven's jar plugin supports automated deployment of jars to local or remote
-    maven repositories.  This powerful feature makes distribution easy, but
-    also makes inadvertent deployment of development jars possible. The
-    setup in 
-    <a href="">
-    <code></code></a> ensures that this does not
-    happen.  This section explains how to deploy jars using maven at apache.
-    </p>
-    <subsection name='Repository structure'>
+    <subsection name="Installing">
-      There are three maven repositories that apache committers should be aware
-      of.  The table below describes each of these repositories.
-      <table><tr><th>External Repository URL</th><th>Function</th></tr>
-      <tr><td></td>
-      <td>deployment location for apache "snapshot" jars. This repository
-      exists for internal apache use only. External projects should
-      <strong>not</strong> use this repository for dependency resolution and
-      apache projects should <strong>not</strong> release code with dependencies
-      snapshot jars.</td></tr>
-      <tr><td></td>
-      <td>deployment location for <strong>released</strong> apache jars.

-      Should not be accessed for dependency resolution by maven builds. Contents
-      are rsynced to ibiblio.</td></tr>
-      <tr><td></td>
-      <td>Default remote repository used by maven. Apache release jars are
-      rsynced every few hours from java-repository to this repository.</td></tr>
-      </table>
+        To install a component in your local repository:
+      <source>mvn install</source>
-    <subsection name='Deploying release jars'>
-      <p>
-      The instructions here automate the process described in step 8 of the
-      <a href="releases/release.html">
-      Apache Commons Release Instructions.</a> It is essential that only
-      <strong>release</strong> jars be deployed in this way and that the
-      <code>artifactId</code> in <code>project.xml</code> be set
-      </p>
+    <subsection name="Source and binary distributions">
-      To deploy a release jar to <code>java-repository</code>, you need to
-      have an ssh key set up (see site deployment section above) and you need
-      to set the <code>maven.repo.list</code> property to refer to 
-      <code>java-repository.</code>  The safest way to do this (to minimize
-      risk of inadvertent production deployment) is to rely on the setup in
-      <a href="">
-</a>, which leaves <code>java-repository</code>
-      off of the repo list, so you have to overrride the list on the command
-      line: 
-      <source>maven -Dmaven.repo.list=apache.releases jar:deploy</source>
-      For this to work, <code>apache.releases</code> has to be configured as
-      <code></code> to point to 
-      <code>java-repository.</code> Jars deployed to 
-      <code>java-repository</code> will be rsynced to <code>ibiblio</code>
-      within a few hours. Immediately after deployment, you should download
-      the jar and verify that: <ul>
-      <li>the name of the jar is correct (matches release)</li>
-      <li>the md5 checksum of the jar matches the release version</li>
-      <li>the md5 checksum of the jar is correct </li>
-      <li>the manifest of the jar is correct</li>
-      </ul>
-      As stated in the <a href="releases/release.html">
-      release instructions</a>, please make sure to update the currentVersion to 
-      end in <code>-SNAPSHOT</code> after pushing out the release jar. 
+        To create the source and binary distributions for a component
+        (and the javadoc and sources jars):
-    </subsection>
-    <subsection name='Deploying snapshot jars'>
+      <source>mvn -Prc package</source>
+    </subsection> 
+    <subsection name="Generating the Site">
-      Assuming the setup in <code></code>, and 
-      correctly set currectVersion (should end in
-      <code>-SNAPSHOT</code>) the following command can be used to deploy a 
-      "snapshot" or "development build" jar to the apache snapshot repository:
-      <source>maven jar:deploy-snapshot</source>
+        To generate a components site:
+      <source>mvn site</source>
+  </section>
+  <section name='Maven POM (pom.xml) configuration'>
+    <p>
+      TODO
+    </p> 

View raw message