Apache Commons – Adding a new Sandbox component

Adding a new Sandbox component

This page describes the steps to setup a new Sandbox Component using component foo as an example.

Subversion Repository

Create the Repository
Create the foo repository in https://svn.apache.org/repos/asf/commons/sandbox/ with the usual folder structure:

          foo
           |
           +--branches
           |
           +--tags
           |
           +--trunk

Add the component to trunks-sandbox
trunks-sandbox uses subversion a svn:externals property to link to the trunks of all the sandbox compoenent - update the svn:externals property for trunks-sandbox to include the new Sandbox component:

          foo https://svn.apache.org/repos/asf/commons/sandbox/foo/trunk

Copying the code
If the code is being brought to the Commons Sandbox from elsewhere at the ASF then please do a subversion copy so that the history of the code is retained.

Create the project structure

Commons components use Maven as their primary build system and it is recommended that the project adopts the default Maven structure:

          trunk
           |
           +--NOTICE.txt
           +--LICENSE.txt
           +--pom.xml
           +--trunk
           +--src
               +--main
               |    |
               |    +--java
               |    +--resources
               |
               +--test
               |    |
               |    +--java
               |
               +--site
                    |
                    +--site.xml
                    +--resources
                    |      |
                    |      +--images
                    |
                    +--xdoc
                         |
                         +--index.xml

See here for a sample Sandbox project.

Using Maven

if you're new to Maven, here are some useful links to get started:

Once you have installed maven the following commands are useful:

          mvn clean              <!-- clean the project -->
          mvn test               <!-- compile and run the tests -->
          mvn package            <!-- compile, run tests and create the jar -->
          mvn site               <!-- create the component site -->

Setup a Maven pom.xml

There is a sample pom.xml in the sample project mentioned above.

Sandbox projects use the in the commons-sandbox-parent pom.xml as there parent, which in turn has the commons-parent as its parent. There are notes on what the commons-parent pom here.

Create a SANDBOX JIRA component

There is a single JIRA projects for all Sandbox components:

http://issues.apache.org/jira/browse/SANDBOX

Create a new component in JIRA, making a note of the componentid
Set commons.jira.componentid property in the component's pom.xml to to the componentid
Run the following command in your new Sandbox project to create a custom issue tracking page:

          mvn commons-build:sandbox-jira-page

Deploy the component site

Deploy the component site to:

          scp://people.apache.org/www/commons.apache.org/sandbox/foo/

Checkout the main Commons Site:

https://svn.apache.org/repos/asf/commons/proper/commons-site/

Update the main Commons site in the following places:

Add the component to the Sandbox menu in the site.xml
Add the component to the Sandbox table on the main indexl.xml
Add the component to the table on the Sandbox indexl.xml