You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@isis.apache.org by da...@apache.org on 2011/06/29 19:17:38 UTC
svn commit: r1141173 -
/incubator/isis/trunk/framework/src/docbkx/guide/isis-contributors-guide.xml
Author: danhaywood
Date: Wed Jun 29 17:17:38 2011
New Revision: 1141173
URL: http://svn.apache.org/viewvc?rev=1141173&view=rev
Log:
updates to contributors guide
Modified:
incubator/isis/trunk/framework/src/docbkx/guide/isis-contributors-guide.xml
Modified: incubator/isis/trunk/framework/src/docbkx/guide/isis-contributors-guide.xml
URL: http://svn.apache.org/viewvc/incubator/isis/trunk/framework/src/docbkx/guide/isis-contributors-guide.xml?rev=1141173&r1=1141172&r2=1141173&view=diff
==============================================================================
--- incubator/isis/trunk/framework/src/docbkx/guide/isis-contributors-guide.xml (original)
+++ incubator/isis/trunk/framework/src/docbkx/guide/isis-contributors-guide.xml Wed Jun 29 17:17:38 2011
@@ -5535,7 +5535,7 @@ gpg --armor --export nnnnnnnn >>KE
url="https://cwiki.apache.org/confluence/display/ISIS/RecreatingMavenArchetypeFromProject">Isis
wiki</ulink>.</para>
- <sect1>
+ <sect1 id="sec.TestingTheQuickstartApp">
<title>Confirm that the quickstart prototype application works
correctly</title>
@@ -6202,19 +6202,16 @@ $ mvn jetty:run</programlisting></entry>
<para>Firstly, export the quickstart prototype into a new
directory:</para>
- <programlisting>mkdir /tmp/archetype
-cd support
-svn export quickstart /tmp/archetype</programlisting>
+ <programlisting>$ mkdir /tmp/archetype
+$ cd .../framework/examples
+$ svn export quickstart /tmp/archetype</programlisting>
<para>This will export all versioned files into
- <filename>/tmp/archetype/quickstart</filename>. Change into this
- directory:</para>
-
- <programlisting>cd /tmp/archetype/quickstart</programlisting>
+ <filename>/tmp/archetype/quickstart</filename>. Switch to this
+ directory and then regenerate the archetype:</para>
- <para>Then, regenerate the archetype:</para>
-
- <programlisting>mvn eclipse:clean clean archetype:create-from-project</programlisting>
+ <programlisting>$ cd /tmp/archetype/quickstart
+$ mvn eclipse:clean clean archetype:create-from-project</programlisting>
</sect1>
<sect1>
@@ -6261,9 +6258,9 @@ svn export quickstart /tmp/archetype</pr
groovy updateGeneratedArchetypeSource.groovy
cd quickstart</programlisting>
- <para>If you want to check this has worked, cd into
+ <para>If you want to check this has worked, switch into
<filename>target/generated-sources/archetype/src/main/resources/archetype-resources</filename>
- and search for .launch files.</para>
+ and search for <filename>.launch</filename> files.</para>
<note>
<para>This script is NOT rerunnable (because it results in the
@@ -6274,16 +6271,97 @@ cd quickstart</programlisting>
<sect1>
<title>Manually edit the generated archetype source</title>
+ <para>The <filename>archetype-metadata.xml</filename> file lists each
+ of the files that constitute the archetype, using a wildcard syntax).
+ Given that the archetype is generated by exporting out of the
+ subversion/Eclipse workspace, all files should be relevant. Even then,
+ it is probably worth reviewing to ensure that no files have been
+ accidentally included:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>there should be no <filename>.log</filename> files
+ lists;</para>
+ </listitem>
+
+ <listitem>
+ <para>there should be no <filename>.settings</filename>
+ directories;</para>
+ </listitem>
+
+ <listitem>
+ <para>there should be no <filename>.project</filename> or
+ <filename>.classpath</filename> files</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>Update the file if necessary.</para>
+ </sect1>
+
+ <sect1>
+ <title>Verify that the archetype works</title>
+
+ <para>Use maven to build and install the archetype into your local
+ repository:</para>
+
+ <programlisting>$ cd /tmp/archetype/quickstart/<filename>target/generated-sources/archetype
+$ mvn clean install</filename></programlisting>
+
+ <para>Next, generate a new application from the archetype:</para>
+
+ <programlisting>$ mkdir /tmp/test
+$ cd /tmp/<filename>test
+$ mvn archetype:generate \
+ -D archetypeCatalog=local \
+ -D archetypeGroupId=org.apache.isis.support \
+ -D archetypeArtifactId=quickstart-archetype \
+ -D groupId=com.mycompany \
+ -D artifactId=myapp</filename></programlisting>
+
+ <para>This should result in a new application in the
+ <filename>myapp</filename> directory. Switch into this
+ directory:</para>
+
+ <programlisting>$ cd myapp</programlisting>
+
+ <para>Then, use the steps described above (<xref
+ linkend="sec.TestingTheQuickstartApp" />) to test the generated
+ application.</para>
+ </sect1>
+
+ <sect1>
+ <title>Commit the archetype</title>
+
+ <para>When you are happy that the archetype is good, it's time to
+ delete the old archetype and commit the new.</para>
+
+ <sect2>
+ <title>Replace archetype in source tree</title>
+
+ <para>First, delete the old archetype:</para>
+
+ <programlisting>$ cd .../trunk/framework
+$ svn delete quickstart-archetype
+$ svn commit -m "deleting old archetype prior to recreating" quickstart-archetype
+</programlisting>
+
+ <para>Now, copy down to generated archetype</para>
+
+ <programlisting>cp -R quickstart/target/generated-sources/archetype quickstart-archetype</programlisting>
+ </sect2>
+
<sect2>
- <title>pom.xml</title>
+ <title>Further manually edits</title>
- <para>Most of the manual edits required are to the
- <filename>pom.xml</filename> file.</para>
+ <para>A number of further edits are required to the archetype to
+ "fit it into" the build.</para>
<sect3>
- <title>Apache License</title>
+ <title>pom.xml</title>
- <para>The first edit is to add in the ASL license:</para>
+ <para>Most of the manual edits required are to the
+ <filename>pom.xml</filename> file. The first edit is to add in the
+ ASL license:</para>
<programlisting><!--
Licensed to the Apache Software Foundation (ASF) under one
@@ -6303,73 +6381,33 @@ cd quickstart</programlisting>
specific language governing permissions and limitations
under the License.
--></programlisting>
- </sect3>
-
- <sect3>
- <title>Parent</title>
<para>The archetype will ultimately be released and distributed
- along with the rest of Isis. Its POM should therefore reference
- the Isis parent:</para>
+ along with the rest of Isis. Its <acronym>POM</acronym> should
+ therefore reference the Isis parent:</para>
<programlisting><parent>
<groupId>org.apache.isis</groupId>
<artifactId>isis</artifactId>
<version>0.x.x-incubating-SNAPSHOT</version>
</parent></programlisting>
- </sect3>
-
- <sect3>
- <title>Name</title>
<para>By default the name of the archetype is derived from the
quickstart prototype application. Although not mandatory, we
should edit it to make it a little more descriptive:</para>
- <programlisting><name>Apache Isis Quickstart Archetype</name</programlisting>
+ <programlisting><name>Apache Isis Quickstart Archetype</name></programlisting>
</sect3>
- </sect2>
-
- <sect2>
- <title>Archetype metadata
- (<filename>src/main/resources/META-INF/maven/archetype-metadata.xml</filename>)</title>
-
- <para>The <filename>archetype-metadata.xml</filename> file lists
- each of the files that constitute the archetype, using a wildcard
- syntax). Given that the archetype is generated by exporting out of
- the subversion/Eclipse workspace, all files should be relevant. Even
- then, it is probably worth reviewing to ensure that no files have
- been accidentally included:</para>
-
- <itemizedlist>
- <listitem>
- <para>there should be no <filename>.log</filename> files
- lists;</para>
- </listitem>
-
- <listitem>
- <para>there should be no <filename>.settings</filename>
- directories;</para>
- </listitem>
-
- <listitem>
- <para>there should be no <filename>.project</filename> or
- <filename>.classpath</filename> files</para>
- </listitem>
- </itemizedlist>
- <para>Update the file if necessary.</para>
- </sect2>
-
- <sect2>
- <title>Remote resource plugin
- (<filename>src/main/appended-resources/supplemental-models.xml</filename>)</title>
+ <sect3>
+ <title>Remote resource plugin
+ (<filename>src/main/appended-resources/supplemental-models.xml</filename>)</title>
- <para>An empty copy of
- <filename>src/main/appended-resources/supplemental-models.xml</filename>
- is also required:</para>
+ <para>An empty copy of
+ <filename>src/main/appended-resources/supplemental-models.xml</filename>
+ is also required:</para>
- <programlisting><?xml version="1.0" encoding="UTF-8"?>
+ <programlisting><?xml version="1.0" encoding="UTF-8"?>
<supplementalDataModels
xmlns="http://maven.apache.org/supplemental-model/1.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
@@ -6378,26 +6416,22 @@ cd quickstart</programlisting>
</supplementalDataModels></programlisting>
- <para>This is as the result of the
- <filename>maven-remote-resource-plugin</filename> plugin inherited
- from the parent <acronym>POM</acronym>.</para>
+ <para>This is as the result of the
+ <filename>maven-remote-resource-plugin</filename> plugin inherited
+ from the parent <acronym>POM</acronym>.</para>
+ </sect3>
</sect2>
- </sect1>
- <sect1>
- <title>Verify that the archetype works</title>
-
- <para>See the <ulink
- url="https://cwiki.apache.org/confluence/display/ISIS/RecreatingMavenArchetypeFromProject">wiki</ulink>
- for further details.</para>
- </sect1>
+ <sect2>
+ <title>Commit the archetype</title>
- <sect1>
- <title>Commit the archetype</title>
+ <para>Finally, commit the new archetype:</para>
- <para>See the <ulink
- url="https://cwiki.apache.org/confluence/display/ISIS/RecreatingMavenArchetypeFromProject">wiki</ulink>
- for further details.</para>
+ <programlisting>svn -N add quickstart-archetype
+svn add quickstart-archetype/pom.xml
+svn add quickstart-archetype/src
+svn commit -m "recreated archetype from the 'quickstart' prototype app" quickstart-archetype</programlisting>
+ </sect2>
</sect1>
</appendix>
</part>