[Skabacca-developer] SF.net SVN: skabacca:[16] trunk
Status: Pre-Alpha
Brought to you by:
triathlon98
|
From: <tri...@us...> - 2010-01-22 19:48:28
|
Revision: 16
http://skabacca.svn.sourceforge.net/skabacca/?rev=16&view=rev
Author: triathlon98
Date: 2010-01-22 19:48:21 +0000 (Fri, 22 Jan 2010)
Log Message:
-----------
layout, breadcrumbs compo, partial docs in docbook
Modified Paths:
--------------
trunk/gui/src/main/resources/org/skabacca/gui/components/EditLayout.tml
trunk/gui/src/main/resources/org/skabacca/gui/components/Layout.tml
trunk/gui/src/main/webapp/css/style.css
trunk/pom.xml
Added Paths:
-----------
trunk/gui/src/main/java/org/skabacca/gui/components/Breadcrumbs.java
trunk/gui/src/main/resources/org/skabacca/gui/components/breadcrumbs.tml
trunk/src/site/docbook/
trunk/src/site/docbook/codingstyle.xml
trunk/src/site/docbook/developers.xml
trunk/src/site/docbook/gettingstarted.xml
trunk/src/site/docbook/index.xml
Added: trunk/gui/src/main/java/org/skabacca/gui/components/Breadcrumbs.java
===================================================================
--- trunk/gui/src/main/java/org/skabacca/gui/components/Breadcrumbs.java (rev 0)
+++ trunk/gui/src/main/java/org/skabacca/gui/components/Breadcrumbs.java 2010-01-22 19:48:21 UTC (rev 16)
@@ -0,0 +1,61 @@
+/*
+ * This file is part of skabacca.
+ *
+ * Copyright belongs to the respective authors, see subversion.
+ *
+ * skabacca is free software: you can redistribute it and/or modify it under the terms of the
+ * Affero GNU General Public License as published by the Free Software Foundation, either version 3 of the License,
+ * or (at your option) any later version.
+ *
+ * Skabacca is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied
+ * warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
+ *
+ * For the full text of the license, see <http://www.gnu.org/licenses/>.
+ */
+
+package org.skabacca.gui.components;
+
+import org.apache.tapestry5.annotations.Property;
+import org.apache.tapestry5.ioc.annotations.Inject;
+import org.apache.tapestry5.services.ApplicationStateManager;
+import org.equanda.t5nav.services.NavigationContext;
+import org.equanda.t5nav.services.NavigationTarget;
+
+/**
+ * Component which displays the breadcrumbs
+ *
+ * @author <a href="mailto:jo...@pr...">Joachim Van der Auwera</a>
+ */
+public class Breadcrumbs
+{
+ @Inject
+ private ApplicationStateManager asoManager;
+
+ @Property
+ private NavigationTarget current;
+
+ @Property
+ private int index;
+
+ public NavigationTarget[] getBreadcrumbs()
+ {
+ if ( !asoManager.exists( NavigationContext.class ) ) return null;
+ NavigationContext currNav = asoManager.get( NavigationContext.class );
+ NavigationTarget[] list = currNav.getRecentReturnTargets();
+ if ( null == list ) return null;
+ int length = list.length;
+ NavigationTarget[] res = new NavigationTarget[length];
+ for ( int i = 0; i < length ; i++ )
+ {
+ res[ length - i - 1 ] = list[ i ];
+ }
+ return res;
+ }
+
+ public Object onActionFromBreadcrumb( int index )
+ {
+ NavigationContext currNav = asoManager.get( NavigationContext.class );
+ if ( null == currNav ) return null;
+ return currNav.getRecentReturnTargets()[ index ].getLink();
+ }
+}
\ No newline at end of file
Modified: trunk/gui/src/main/resources/org/skabacca/gui/components/EditLayout.tml
===================================================================
--- trunk/gui/src/main/resources/org/skabacca/gui/components/EditLayout.tml 2010-01-21 14:42:00 UTC (rev 15)
+++ trunk/gui/src/main/resources/org/skabacca/gui/components/EditLayout.tml 2010-01-22 19:48:21 UTC (rev 16)
@@ -1,4 +1,4 @@
-dit<t:layout xmlns:t="http://tapestry.apache.org/schema/tapestry_5_0_0.xsd">
+<t:layout xmlns:t="http://tapestry.apache.org/schema/tapestry_5_0_0.xsd">
<t:parameter name="title">
<t:delegate to="title"/>
Modified: trunk/gui/src/main/resources/org/skabacca/gui/components/Layout.tml
===================================================================
--- trunk/gui/src/main/resources/org/skabacca/gui/components/Layout.tml 2010-01-21 14:42:00 UTC (rev 15)
+++ trunk/gui/src/main/resources/org/skabacca/gui/components/Layout.tml 2010-01-22 19:48:21 UTC (rev 16)
@@ -48,7 +48,7 @@
-->
<div id="layout-topbar">
<div id="layout-topbar-right"><t:delegate to="context"/></div>
- <div id="layout-breadcrumbs"><div id="layout-breadcrumbs-title"><t:delegate to="title"/></div>breadcrumbs bar</div>
+ <div id="layout-breadcrumbs"><div id="layout-breadcrumbs-title"><t:delegate to="title"/></div><t:breadcrumbs/></div>
</div>
<div id="layout-info"><t:delegate to="sidebar"/></div>
@@ -58,11 +58,9 @@
<t:errors/>
<t:body/>
</div>
- <div id="layout-buttons"><t:delegate to="buttons"/></div>
- </div>
</div>
-
+</div>
<div id="footer">
<div id="layout-buttons"><t:delegate to="buttons"/></div>
<p id="footermsg"><a href="http://www.skabacca.org//">${equanda-message:layout.PoweredBy}</a></p>
Added: trunk/gui/src/main/resources/org/skabacca/gui/components/breadcrumbs.tml
===================================================================
--- trunk/gui/src/main/resources/org/skabacca/gui/components/breadcrumbs.tml (rev 0)
+++ trunk/gui/src/main/resources/org/skabacca/gui/components/breadcrumbs.tml 2010-01-22 19:48:21 UTC (rev 16)
@@ -0,0 +1,5 @@
+<div xmlns:t="http://tapestry.apache.org/schema/tapestry_5_0_0.xsd">
+ <t:loop source="breadcrumbs" value="current" index="index" volatile="true">
+ > <t:actionlink t:id="breadcrumb" context="index">${current.title}</t:actionlink>
+ </t:loop>
+</div>
Modified: trunk/gui/src/main/webapp/css/style.css
===================================================================
--- trunk/gui/src/main/webapp/css/style.css 2010-01-21 14:42:00 UTC (rev 15)
+++ trunk/gui/src/main/webapp/css/style.css 2010-01-22 19:48:21 UTC (rev 16)
@@ -87,6 +87,7 @@
width: 100%;
background: black;
}
+
#footer {
position: fixed;
bottom: 0;
@@ -94,6 +95,28 @@
width: 100%;
background: black;
}
+#layout-buttons {
+ padding : 8px;
+ text-align: center;
+}
+#footermsg {
+ position: fixed;
+ right: 0;
+ bottom: 0;
+ text-align: right;
+}
+#footermsg a:link,
+#footermsg a:visited,
+#footermsg a:active {
+ color: #CCC;
+ text-decoration: underline;
+}
+#footermsg a:hover {
+ color: white;
+ text-decoration: none;
+}
+
+
#body {
margin: 42px 0;
}
@@ -117,7 +140,6 @@
#layout-breadcrumbs { position:fixed; top:16px; left:200px; right:0; height:16px; background-color: lightgray; text-align:center; }
#layout-breadcrumbs-title { float: left; font-weight: bold; padding-left: 6px; padding-right: 6px; }
#layout-main { position:fixed; top:32px; bottom:20px; left:200px; right:140px; overflow:auto; overflow-y:scroll; background-color:white; padding:10px; }
-#layout-buttons { position:fixed; left:200px; right:140px; bottom:0; background-color:lightgray; text-align:center; }
#layout-info { position:fixed; width:133px; right:0; top:32px; bottom:0; background-color:beige; border-left: 1px dashed black; overflow-x:hidden; overflow-y:scroll; padding:3px }
*/
Modified: trunk/pom.xml
===================================================================
--- trunk/pom.xml 2010-01-21 14:42:00 UTC (rev 15)
+++ trunk/pom.xml 2010-01-22 19:48:21 UTC (rev 16)
@@ -6,7 +6,7 @@
<version>1.0-SNAPSHOT</version>
<artifactId>skabacca</artifactId>
<packaging>pom</packaging>
- <name>Skill + Knowledge + Behaviour = Competence, Competence Analyser</name>
+ <name>Skill + Knowledge + Behaviour = Competency, Competency Analyser</name>
<modules>
<module>core</module>
Added: trunk/src/site/docbook/codingstyle.xml
===================================================================
--- trunk/src/site/docbook/codingstyle.xml (rev 0)
+++ trunk/src/site/docbook/codingstyle.xml 2010-01-22 19:48:21 UTC (rev 16)
@@ -0,0 +1,329 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
+"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
+<!--
+ ~ This file is part of Geomajas, a component framework for building
+ ~ rich Internet applications (RIA) with sophisticated capabilities for the
+ ~ display, analysis and management of geographic information.
+ ~ It is a building block that allows developers to add maps
+ ~ and other geographic data capabilities to their web applications.
+ ~
+ ~ Copyright 2008-2010 Geosparc, http://www.geosparc.com, Belgium
+ ~
+ ~ This program is free software: you can redistribute it and/or modify
+ ~ it under the terms of the GNU Affero General Public License as
+ ~ published by the Free Software Foundation, either version 3 of the
+ ~ License, or (at your option) any later version.
+ ~
+ ~ This program is distributed in the hope that it will be useful,
+ ~ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ ~ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ ~ GNU Affero General Public License for more details.
+ ~
+ ~ You should have received a copy of the GNU Affero General Public License
+ ~ along with this program. If not, see <http://www.gnu.org/licenses/>.
+ -->
+<article id="release" lang="en">
+ <title>Coding quality and style</title>
+
+ <toc />
+
+ <!--
+References
+- http://maven.apache.org/developers/conventions/code.html
+- http://docs.jboss.org/process-guide/en/html/coding.html
+- http://equanda.org/developers.html
+- http://svn.collab.net/repos/svn/trunk/www/hacking.html
+- http://java.sun.com/docs/codeconv/
+- http://geosoft.no/development/javastyle.html (!)
+- http://192.220.96.201/essays/java-style/single-page.html
+- http://gee.cs.oswego.edu/dl/html/javaCodingStd.html
+- http://www.ambysoft.com/essays/javaCodingStandards.html
+- http://docs.codehaus.org/display/GEOT/5+Project+Conventions
+-->
+
+ <para>As a general note, the coding style and naming conventions should be
+ adhered to. Some parts are even checked by the checkstyle maven plugin.
+ However, deviations are always allowed when this enhances code readability
+ (but only when checkstyle accepts it, otherwise the build will fail).</para>
+
+ <para>You can configure a formatter to apply this style in your favourite
+ IDE (see also at the bottom). You can be liberal on applying this on new
+ code, but be prudent when applying these to the existing code base. Code
+ style changes make revision changes a lot more difficult and should thus be
+ limited. If there is a need to reformat existing code, then this should be
+ done in a separate commit.</para>
+
+ <section>
+ <title>Class, method and variable names</title>
+
+ <para>Rules</para>
+
+ <itemizedlist>
+ <listitem>Use meaningful names. Especially class and method names should
+ explain their purpose.</listitem>
+
+ <listitem>For class, method and (non-static) variable names, use
+ camelCase to separate the words, not underscores. For abbreviations,
+ capitalize he first letter, lower case for the others.</listitem>
+
+ <listitem>Class names start with a capital, for example
+ "EquandaException".</listitem>
+
+ <listitem>Method and (non-static) variable names start lower case, for
+ example "getMessage".</listitem>
+
+ <listitem>All static variables should have capitalized names with words
+ separated by underscores.</listitem>
+
+ <listitem>Package names are all lower case and should be
+ singular.</listitem>
+
+ <listitem>Use getXxx/setXxx/isXxx.</listitem>
+
+ <listitem>Abbreviations and acronyms should not be uppercase when used
+ as name (for example, use "exportHtml()").</listitem>
+
+ <listitem>All names should be written in English.</listitem>
+
+ <listitem>The terms get/set must be used where an attribute is accessed
+ directly.</listitem>
+
+ <listitem>"is" prefix should be used for boolean variables and methods.
+ In some cases, when this is more readable, "has", "can" or "should" can
+ also be used as prefix.</listitem>
+
+ <listitem>Complement names must be used for complement entities. These
+ include get/set, add/remove, create/destroy, start/stop, insert/delete,
+ increment/decrement, old/new, begin/end, first/last, up/down, min/max,
+ next/previous, old/new, open/close, show/hide, suspend/resume,
+ etc.</listitem>
+
+ <listitem>Exception classes should be suffixed with
+ Exception.</listitem>
+ </itemizedlist>
+
+ <para>Recommendations</para>
+
+ <itemizedlist>
+ <listitem>Usually class names are nouns and method names are
+ verbs.</listitem>
+
+ <listitem>Generic variables should have the same name as their
+ type.</listitem>
+
+ <listitem>Variables with a large scope should have long names, variables
+ with a small scope can have short names. Scratch variables used for
+ temporary storage or indices are best kept short. A programmer reading
+ such variables should be able to assume that its value is not used
+ outside a few lines of code. Common scratch variables for integers are
+ i, j, k, m, n and for characters c and d.</listitem>
+
+ <listitem>The name of the object is implicit, and should be avoided in a
+ method name. For example, use "line.getLength()" instead of
+ "line.getLineLength()". The latter might seem natural in the class
+ declaration, but proves superfluous in use, as shown in the
+ example.</listitem>
+
+ <listitem>The term compute can be used in methods where something is
+ computed.</listitem>
+
+ <listitem>The term find can be used in methods where something is looked
+ up.</listitem>
+
+ <listitem>The term initialize can be used where an object or a concept
+ is established.</listitem>
+
+ <listitem>Plural form should be used on names representing a collection
+ of objects.</listitem>
+
+ <listitem>Negated boolean variable names must be avoided.</listitem>
+
+ <listitem>Default interface implementations can be prefixed by Default.
+ However, if it is not expected that there will even be another
+ implementation, it can be a lot more natural to suffix with "Impl"
+ instead.</listitem>
+
+ <listitem>Singleton classes should return their sole instance through
+ method getInstance(), should have a private constructor and be declared
+ final.</listitem>
+
+ <listitem>Functions (methods returning an object) should be named after
+ what they return and procedures (void methods) after what they
+ do.</listitem>
+ </itemizedlist>
+
+ <section><title>Comment</title>Each file should have the correct copyright
+ notice at the start of the file. <programlisting>/*
+ * This file is part of skabacca.
+ *
+ * Copyright belongs to the respective authors, see subversion.
+ *
+ * skabacca is free software: you can redistribute it and/or modify it under the terms of the
+ * Affero GNU General Public License as published by the Free Software Foundation, either version 3 of the License,
+ * or (at your option) any later version.
+ *
+ * Skabacca is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied
+ * warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
+ *
+ * For the full text of the license, see <http://www.gnu.org/licenses/>.
+ */</programlisting><itemizedlist>
+ <listitem>The copyright message should be at the top of the
+ file.</listitem>
+
+ <listitem>Each class and interface should have class comments
+ indicating the purpose of the class.</listitem>
+
+ <listitem>Public methods should be commented if the meaning is not
+ entirely clear from method and parameter names (is it ever?). When the
+ method overrides or implements a method, then repeating the javadoc is
+ not needed (it is recommended to us "@inheritedDoc").</listitem>
+
+ <listitem>Comments in the code are recommended when they explain a
+ block of code or when they explain why things are done in a certain
+ way. Repeating the code in human readable wording is
+ wasteful.</listitem>
+
+ <listitem>Use "@todo" comments to indicate shortcuts or hacks which
+ should be fixed. Better still is just to do it right and not have the
+ shortcut.</listitem>
+
+ <listitem>All comments should be written in English.</listitem>
+
+ <listitem>Comments should be indented relative to their position in
+ the code.</listitem>
+
+ <listitem>
+ <para>Javadoc comments should be active, not descriptive (for
+ example on method "getXxx()" the comment could be "Get xxx").</para>
+ </listitem>
+ </itemizedlist></section>
+
+ <section>
+ <title>Claim your code</title>
+
+ <para>Be proud of your code and take responsibility of your changes.
+ When making any kind of significant changes (not for reformatting,
+ fixing typing errors or renaming), add your full name (optionally
+ including e-mail link) at the bottom of the authors list in the class
+ comments.</para>
+ </section>
+
+ <section>
+ <title>Code layout</title>
+
+ <para>See the example below</para>
+
+ <programlisting>/*
+ * This file is part of skabacca.
+ *
+ * Copyright belongs to the respective authors, see subversion.
+ *
+ * skabacca is free software: you can redistribute it and/or modify it under the terms of the
+ * Affero GNU General Public License as published by the Free Software Foundation, either version 3 of the License,
+ * or (at your option) any later version.
+ *
+ * Skabacca is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied
+ * warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
+ *
+ * For the full text of the license, see <http://www.gnu.org/licenses/>.
+ */
+
+package org.skabacca.bladibla;
+
+/**
+ * Page for importing/updating a portfolio from one of a selection of formats.
+ *
+ * @author <a href="mailto:au...@em...">Author's name</a>
+ * @author Another Author's Name
+ */
+@Annotation( param1 = "value1", param2 = "value2" )
+public class Foo
+ implements Serializable
+{
+ int[] x = new int[] { 1, 3, 5, 6, 7, 87, 1213, 2 };
+
+ /**
+ * Do something
+ *
+ * @param x some data
+ * @param y more data
+ */
+ public void foo( int x, int y )
+ throws Exception
+ {
+ for ( int i = 0; i < x ; i++ )
+ {
+ y += ( y ^ 0x123 ) << 2;
+ }
+ do
+ {
+ try
+ {
+ if ( 0 < x && x < 10 )
+ {
+ while ( x != y )
+ {
+ x = f( x * 3 + 5 );
+ }
+ }
+ else
+ {
+ synchronized ( this )
+ {
+ switch ( e.getCode() )
+ {
+ //...
+ }
+ }
+ }
+ }
+ catch ( MyException e )
+ {}
+ finally
+ {
+ int[] arr = (int[]) g( y );
+ x = y >= 0 ? arr[ y ] : -1;
+ }
+ }
+ while ( true );
+ }
+}</programlisting>
+
+ <para>The codingstyle is optimized for readability and thus uses a lot
+ of whitespace both horizontally as vertically.</para>
+
+ <itemizedlist>
+ <listitem>The code is written with the right margin at 120 characters
+ and lines should not be longer than that if possible.</listitem>
+
+ <listitem>All indents should be done using four spaces, no tabs
+ !</listitem>
+
+ <listitem>Braces are always on separate lines. The only exception is
+ for empty blocks and single line ifs and for/while loops.</listitem>
+
+ <listitem>Always use spaces inside brackets.</listitem>
+
+ <listitem>Spaces around operators.</listitem>
+
+ <listitem>No wildcards allowed on import statements.</listitem>
+
+ <listitem>Always use braces when the body is not on the same line as
+ the if, for, while, do-while.</listitem>
+
+ <listitem>Array specifiers must be attached to the type not the
+ variable.</listitem>
+
+ <listitem>Class variables should never be declared public.</listitem>
+
+ <listitem>Logical units within a block should be separated by one
+ blank line.</listitem>
+ </itemizedlist>
+
+ <para>We have an <ulink url="equanda.xml">IntelliJ IDEA</ulink>
+ formatter which can be used. However, be careful not to change the
+ entire formatting of a class.</para>
+ </section>
+ </section>
+</article>
Added: trunk/src/site/docbook/developers.xml
===================================================================
--- trunk/src/site/docbook/developers.xml (rev 0)
+++ trunk/src/site/docbook/developers.xml 2010-01-22 19:48:21 UTC (rev 16)
@@ -0,0 +1,293 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
+"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
+<!--
+ ~ This file is part of Geomajas, a component framework for building
+ ~ rich Internet applications (RIA) with sophisticated capabilities for the
+ ~ display, analysis and management of geographic information.
+ ~ It is a building block that allows developers to add maps
+ ~ and other geographic data capabilities to their web applications.
+ ~
+ ~ Copyright 2008-2010 Geosparc, http://www.geosparc.com, Belgium
+ ~
+ ~ This program is free software: you can redistribute it and/or modify
+ ~ it under the terms of the GNU Affero General Public License as
+ ~ published by the Free Software Foundation, either version 3 of the
+ ~ License, or (at your option) any later version.
+ ~
+ ~ This program is distributed in the hope that it will be useful,
+ ~ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ ~ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ ~ GNU Affero General Public License for more details.
+ ~
+ ~ You should have received a copy of the GNU Affero General Public License
+ ~ along with this program. If not, see <http://www.gnu.org/licenses/>.
+ -->
+<article id="release" lang="en">
+ <title>Developers information</title>
+
+ <toc />
+
+ <section>
+ <title>maven targets, profiles, variables</title>
+
+ <para>There are two main ways to install, either just compiling, running
+ the simple tests and installing, or running the full testsuite which does
+ integration tests by deploying some sample stuff into a jboss
+ instance.</para>
+
+ <para>You can choose by using one of the following targets.</para>
+
+ <programlisting>mvn install
+mvn -Dfulltest install
+</programlisting>
+
+ <para>To be able to run the full test suite, you need to include a profile
+ in your maven local settings (.m2/settings.xml).</para>
+
+ <programlisting><settings>
+ <profiles>
+ <profile>
+ <id>dev-joachim</id>
+ <properties>
+ <!-- selenium properties-->
+ <firefox.path>firefox /usr/lib/firefox/firefox-bin</firefox.path>
+
+ <equanda.db.url>jdbc:firebirdsql:localhost/3050:/home/joachim/data/equanda.fdb</equanda.db.url>
+ <equanda.db.login>sysdba</equanda.db.login>
+ <equanda.db.password>masterkey</equanda.db.password>
+ <equanda.db.location>/home/joachim/data/equanda.fdb</equanda.db.location>
+ <equanda.db.empty>/home/joachim/data/equanda-empty.fdb</equanda.db.empty>
+ <equanda.cargo.wait>true</equanda.cargo.wait>
+ <!-- jboss properties-->
+ <equanda.jboss.home>/home/joachim/java/equandajboss</equanda.jboss.home>
+ <equanda.jboss.config>equanda</equanda.jboss.config>
+ <equanda.jboss.host>localhost</equanda.jboss.host>
+ <equanda.jboss.port>8080</equanda.jboss.port>
+ <equanda.jboss.jvmargs>
+ -server -Xms256m -Xmx382m -XX:MaxPermSize=128m -Dsun.net.inetaddr.ttl=15
+ -Dsun.rmi.dgc.client.gcInterval=3600000
+ -Dsun.rmi.dgc.server.gcInterval=3600000
+ </equanda.jboss.jvmargs>
+ <equanda.jboss.logging>medium</equanda.jboss.logging>
+
+ </properties>
+ </profile>
+ </profiles>
+ <activeProfiles>
+ <activeProfile>dev-joachim</activeProfile>
+ </activeProfiles>
+
+ <pluginGroups>
+ <pluginGroup>org.equanda</pluginGroup>
+ </pluginGroups>
+
+</settings></programlisting>
+ </section>
+
+ <section><title>Documentation</title><para>All documentation is written in
+ docbook format to allow both PDF and HTML output formats. </para>To generate
+ the project site, use <programlisting>mvn site</programlisting><para>For
+ editing the docbook files, we recommend using <ulink
+ url="http://www.xmlmind.com/xmleditor/">XMLMind</ulink>. The personal
+ version is free and can (at the time of writing) be used for editing open
+ source documentation. </para><para>The docbook files are currently formatted
+ using XMLMind. When using another tool for editing, please keep the current
+ formatting to assure diffs remain usable. </para></section>
+
+ <section>
+ <title>subversion, commits</title>
+
+ <para>All SVN commits should include the JIRA issue number at the start of
+ the commit message, and a short description of the work done. The JIRA
+ issue number allows linking the commits with the issues (as can be seen in
+ JIRA), the short message allows persons to know what is happening without
+ referring to JIRA. The only times JIRA issue number are not needed is for
+ making "obvious" changes like fixing typos.</para>
+
+ <para>Commits should be grouped by issue as much as possible/sensible
+ (better two commits than one commit for fixing two issues, better one
+ commit of five files than five commits of one file (for one
+ issue)).</para>
+
+ <para>Development of the "latest-and-greatest" version happens in
+ "trunk".</para>
+
+ <para>When a release is cut, a tag with the release version as name is
+ created. The release should be built from the tagged files.</para>
+
+ <para>After each commit, the system should still compile and all test
+ cases should still succeed. There is a continuous integration engine
+ (Hudson) which verifies this and sends messages to the developers mailing
+ list on failures.</para>
+ </section>
+
+ <section>
+ <title>Coding</title>
+
+ <para>Note that details about coding style and naming are on the <ulink
+ url="codingstyle.html">coding style</ulink> page.</para>
+
+ <section>
+ <title>Logging</title>
+
+ <itemizedlist>
+ <listitem>
+ <para>For debug level messages, always use
+ <code>isDebugEnabled()</code>.</para>
+ </listitem>
+
+ <listitem>all logging is done through log4j, logger is created using
+ <programlisting>private static final Logger log = Logger.getLogger( ContainingClassName.class );</programlisting></listitem>
+
+ <listitem>logging levels<table>
+ <title>logging levels</title>
+
+ <tgroup cols="3">
+ <thead>
+ <row>
+ <entry align="center">log level</entry>
+
+ <entry align="center">default on</entry>
+
+ <entry>use</entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry>ERROR</entry>
+
+ <entry>yes</entry>
+
+ <entry>major problems, should always be visible in logs and
+ are likely to require action from a person (to fix the
+ condition or assure it does not happen again). Indicates
+ that something is seriously wrong.</entry>
+ </row>
+
+ <row>
+ <entry>WARN</entry>
+
+ <entry>yes</entry>
+
+ <entry>warning about potential problems. Should always be
+ visible in logs and a person will probably need to assess
+ whether this is harmless or should be treated as an
+ error.</entry>
+ </row>
+
+ <row>
+ <entry>INFO</entry>
+
+ <entry>yes</entry>
+
+ <entry>important information. You can assume this level is
+ on in production, so it should be carefully considered
+ whether this level is appropriate. In general only used to
+ indicate service status (started, stopped).</entry>
+ </row>
+
+ <row>
+ <entry>DEBUG</entry>
+
+ <entry>no</entry>
+
+ <entry>logging information which is detailed enough to know
+ what is happening in the system, without flooding the
+ logs.</entry>
+ </row>
+
+ <row>
+ <entry>TRACE</entry>
+
+ <entry>no</entry>
+
+ <entry>very detailed logging, probably only making sense to
+ the developer of the code.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table></listitem>
+
+ <listitem>When an exception is caught and (another exception) thrown
+ you should not log the exception. You should however include the cause
+ in the newly thrown exception.</listitem>
+ </itemizedlist>
+ </section>
+
+ <section>
+ <title>Unit testing</title>
+
+ <para>Unit testing: At least each class implementing the public API
+ should have a unit test, testing all methods. For testing JUnit is
+ used.</para>
+
+ <itemizedlist>
+ <listitem>Advantages of unit testing: <itemizedlist>
+ <listitem>
+ <para>Capturing a <ulink
+ url="http://jira.geomajas.org/">JIRA</ulink> bug report in a
+ reproducible manner.</para>
+ </listitem>
+
+ <listitem>Allowing you to specify exactly the behaviour you want,
+ before you start coding.</listitem>
+ </itemizedlist></listitem>
+
+ <listitem>How unit testing should be done: <itemizedlist>
+ <listitem>If you are testing
+ src/main/java/org/geomajas/ToBeTestedClass.java, create a class
+ src/test/java/org/geomajas/ToBeTestedClassTest.java. Actual test
+ methods have a name starting with "test". The class itself should
+ extend jnit.framework.TestCase.</listitem>
+
+ <listitem>
+ <para>The test will automatically be run when running "<code>mvn
+ install</code>".</para>
+ </listitem>
+ </itemizedlist></listitem>
+
+ <listitem>Integration tests should also be provided. These can also be
+ used for testing the user interface (thanks to selenium).</listitem>
+ </itemizedlist>
+ </section>
+
+ <section>
+ <title>Exception handling</title>
+
+ <para>*Never* throw away exception, either log them or throw them again
+ (possibly wrapped). Do not log and throw, this only clutters log files
+ with duplicate exceptions.</para>
+
+ <para>Do not wrap exceptions unnecessarily (so no
+ <code>EquandaException</code> caused by a <code>EquandaException</code>)
+ unless you add additional information in the message.</para>
+
+ <para>When wrapping an exception, always include the cause.</para>
+ </section>
+
+ <section>
+ <title>Refactoring</title>
+
+ <para>Changes in the (public) API use a "deprecate, then remove" cycle.
+ It should be marked "deprecated" in at least one minor version before it
+ can be removed in the next major version.</para>
+ </section>
+
+ <section>
+ <title>File encoding</title>
+
+ <para>All source files, including .properties files should use UTF-8
+ encoding.</para>
+ </section>
+
+ <section>
+ <title>Other</title>
+
+ <para>For the directory structure and file locations, we follow standard
+ maven conventions (see <ulink
+ url="http://maven.apache.org/guides/introduction/introduction-to-the-standard-directory-layout.html">http://maven.apache.org/guides/introduction/introduction-to-the-standard-directory-layout.html</ulink>).</para>
+ </section>
+ </section>
+</article>
Added: trunk/src/site/docbook/gettingstarted.xml
===================================================================
--- trunk/src/site/docbook/gettingstarted.xml (rev 0)
+++ trunk/src/site/docbook/gettingstarted.xml 2010-01-22 19:48:21 UTC (rev 16)
@@ -0,0 +1,23 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
+"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
+<article id="docbook" lang="en">
+ <title>Page title</title>
+
+ <toc />
+
+ <para>
+ <note>
+ <para><emphasis>warning</emphasis> : this documentation is still
+ somewhat incomplete. We are working hard to improve both the feature set
+ and the documentation. So do have a browse around, but definitely come
+ back later to see how things evolve.</para>
+ </note>
+ </para>
+
+ <section>
+ <title>Section</title>
+
+ <para>A sample paragraph.</para>
+ </section>
+</article>
Added: trunk/src/site/docbook/index.xml
===================================================================
--- trunk/src/site/docbook/index.xml (rev 0)
+++ trunk/src/site/docbook/index.xml 2010-01-22 19:48:21 UTC (rev 16)
@@ -0,0 +1,23 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
+"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
+<article id="docbook" lang="en">
+ <title>Page title</title>
+
+ <toc />
+
+ <para>
+ <note>
+ <para><emphasis>warning</emphasis> : this documentation is still
+ somewhat incomplete. We are working hard to improve both the feature set
+ and the documentation. So do have a browse around, but definitely come
+ back later to see how things evolve.</para>
+ </note>
+ </para>
+
+ <section>
+ <title>Section</title>
+
+ <para>A sample paragraph.</para>
+ </section>
+</article>
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|