Update readme with Mike's ML post to the alpha1 vote thread

git-svn-id: http://svn.us.apache.org/repos/asf/tuscany@769292 13f79535-47bb-0310-9956-ffa450edef68

1 files changed, 143 insertions, 18 deletions

diff --git a/maven-plugins/trunk/maven-zip-plugin/README b/maven-plugins/trunk/maven-zip-plugin/README
index 67fb9c1319..671e7ccc40 100644
--- a/maven-plugins/trunk/maven-zip-plugin/README
+++ b/maven-plugins/trunk/maven-zip-plugin/README
@@ -1,25 +1,35 @@
-This module is a Maven plugin which supports using a packaging of zip in a pom.xml to 
-create a zip format SCA contribution.
+User Documentation
+__________________
 
-The main difference between an SCA zip and jar contribution is that a zip contribution supports
-nesting jar's within the zip and having those nested jar's available within the classloader
-of the contribution. This enables packaging application classes and any 3rd party jars they
-depend on together in one contribution.
+This module is a Maven plugin which supports the creation of a zip format SCA contribution from
+the contents of a Maven project. An SCA contribution can be deployed to the Tuscany SCA runtime
+and run as an application.
 
-The zip plugin builds a zip archive of the project and includes any dependency jars used by 
-the project inside the zip in a folder name "lib" 
-     
-TODOs: 
-- make the "lib/" folder where the dependent jars go configurable
-- make which dependencies get included configurable 
-  (currently its those with compile or runtime scope)
+One of the main uses for an SCA zip contribution is that the SCA zip contribution can contain 
+Java jar files within the zip and those jar files are available to the Java classloader of the 
+contribution.  This enables the packaging of application Java classes along with any other Jar files
+which they depend on in one contribution file. As a result the single zip file can hold everything
+that's needed for the SCA application other than the Tuscany runtime itself - in one neat package.
+
+The zip Maven plugin is used by adding a section into <build/> portion of the pom.xml of the Maven 
+project which relates to the maven zip plugin.  It is also necessary for the packaging of the output 
+of the project to be declared as "zip".  Then run Maven in the project.
+
+This zip plugin builds the output of the project as an SCA zip archive and it includes any
+jar files from dependencies declared by the project, where those dependency jar files are placed
+into the zip archive in a folder with the name "lib".
+
+An example pom.xml including the zip plugin statements:
 
-An example pom.xml:
+   ...
+   <!-- output packaging format is "zip" -->
    <packaging>zip</packaging>
    ... 
    <build>
       ...
+      <!-- section referencing the Tuscany zip plugin -->
       <plugins>
+      ...
          <plugin>
             <groupId>org.apache.tuscany.maven.plugins</groupId>
             <artifactId>maven-zip-plugin</artifactId>
@@ -29,13 +39,120 @@ An example pom.xml:
       </plugins>
    </build>
 
+(It is probably a good idea to now give an example of a complete POM containing one this stuff so that
+users get the full context - I've attached one here, but it isn't the best example)
+
+<?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>
+
+	<parent>
+        <artifactId>tuscany-sca</artifactId>
+        <groupId>org.apache.tuscany.sca</groupId>
+        <version>2.0-SNAPSHOT</version>
+    </parent>
+	<groupId>org.inglenook.test1</groupId>
+	<artifactId>mikestest</artifactId>
+	<packaging>zip</packaging>
+	<version>1.0-SNAPSHOT</version>
+	<name>quickstart</name>
+
+	<dependencies>
+		<!--  TUSCANY DEPENDENCIES -->
+            <dependency>
+               <groupId>org.apache.tuscany.sca</groupId>
+               <artifactId>tuscany-sca-api</artifactId>
+               <version>${tuscany.version}</version>
+               <scope>provided</scope>
+            </dependency>
+
+		<!--  AN EXAMPLE APPLICATION DEPENDENCY TO BE INCLUDED IN ZIP -->
+            <dependency>
+               <groupId>commons-io</groupId>
+               <artifactId>commons-io</artifactId>
+               <version>1.4</version>
+            </dependency>
+
+		<!--  JUNIT DEPENDENCY FOR TESTING -->
+		<dependency>
+			<groupId>junit</groupId>
+			<artifactId>junit</artifactId>
+			<version>3.8.2</version>
+			<scope>test</scope>
+		</dependency>
+
+	</dependencies>
+	<build>
+            <defaultGoal>install</defaultGoal>
+            <finalName>${artifactId}</finalName>
+		<resources>
+			<resource>
+				<directory>src/main/resources</directory>
+			</resource>
+			<resource>
+				<directory>src/main/java</directory>
+				<includes>
+					<include>**</include>
+				</includes>
+				<excludes>
+					<exclude>**/*.java</exclude>
+				</excludes>
+			</resource>
+		</resources>
+		<testResources>
+			<testResource>
+				<directory>src/test/java</directory>
+				<includes>
+					<include>**</include>
+				</includes>
+				<excludes>
+					<exclude>**/*.java</exclude>
+				</excludes>
+			</testResource>
+		</testResources>
+		<plugins>
+			<plugin>
+				<inherited>true</inherited>
+				<groupId>org.apache.maven.plugins</groupId>
+				<artifactId>maven-compiler-plugin</artifactId>
+				<configuration>
+					<source>1.5</source>
+					<target>1.5</target>
+					<optimise>true</optimise>
+					<debug>true</debug>
+				</configuration>
+			</plugin>
+			<plugin>
+				<groupId>org.apache.maven.plugins</groupId>
+				<artifactId>maven-eclipse-plugin</artifactId>
+				<configuration>
+					<downloadSources>true</downloadSources>
+				</configuration>
+			</plugin>
+			<plugin>
+				<groupId>org.apache.tuscany.maven.plugins</groupId>
+				<artifactId>maven-zip-plugin</artifactId>
+                        <extensions>true</extensions>
+			</plugin>
+			<plugin>
+				<groupId>org.apache.tuscany.maven.plugins</groupId>
+				<artifactId>maven-tuscany-plugin</artifactId>
+			</plugin>
+		</plugins>
+	</build>
+	<properties>
+		<tuscany.version>2.0-SNAPSHOT</tuscany.version>
+	</properties>
+	</project>
 
------------------------------------------------------------------------------
-This Tuscany module includes much code copied from the Maven WAR plugin 2.0.2 
-written by the Apache Maven team.
------------------------------------------------------------------------------
 
+TODOs: 
+- make the "lib/" folder where the dependent jars go configurable
+- make which dependencies get included configurable 
+  (currently its those with compile or runtime scope)
 
+---------------------------------
 Building and releasing the plugin
 ---------------------------------
 
@@ -96,3 +213,11 @@ After a successfule vote copy the staging artifacts to the live repository, eg:
 
 cp -p -v -R  maven-zip-plugin-alpha1/org/apache/tuscany/maven/plugins/ /x1/www/people.apache.org/repo/m2-ibiblio-rsync-repository/org/apache/tuscany/maven/plugins
 
+-----------------------------------------------------------------------------
+This Tuscany module includes much code copied from the Maven WAR plugin 2.0.2 
+written by the Apache Maven team.
+-----------------------------------------------------------------------------
+
+
+
+