Author: hiranya
Date: Fri Dec 23 05:31:34 2011
New Revision: 1222568
URL: http://svn.apache.org/viewvc?rev=1222568&view=rev
Log:
Documentation update
Added:
synapse/branches/2.1/src/site/xdoc/dev/best-practices.xml
Modified:
synapse/branches/2.1/src/site/site.xml
synapse/branches/2.1/src/site/xdoc/userguide/extending.xml
synapse/branches/2.1/src/site/xdoc/userguide/mediators.xml
synapse/branches/2.1/src/site/xdoc/userguide/transports.xml
synapse/branches/2.1/src/site/xdoc/userguide/upgrading.xml
Modified: synapse/branches/2.1/src/site/site.xml
URL:
http://svn.apache.org/viewvc/synapse/branches/2.1/src/site/site.xml?rev=1222568&r1=1222567&r2=1222568&view=diff
==============================================================================
--- synapse/branches/2.1/src/site/site.xml (original)
+++ synapse/branches/2.1/src/site/site.xml Fri Dec 23 05:31:34 2011
@@ -51,9 +51,8 @@
</menu>
<menu name="Developer Resources">
<item name="Developer Guide " href="dev/developer-guide.html"/>
- <item name="Developer Best Practices"/>
+ <item name="Development Best Practices"
href="dev/best-practices.html"/>
<item name="Release Process" href="dev/release-process.html"/>
- <item name="How to Contribute"/>
</menu>
<menu name="Project Details">
<item name="Overview" href="project-info.html"/>
Added: synapse/branches/2.1/src/site/xdoc/dev/best-practices.xml
URL:
http://svn.apache.org/viewvc/synapse/branches/2.1/src/site/xdoc/dev/best-practices.xml?rev=1222568&view=auto
==============================================================================
--- synapse/branches/2.1/src/site/xdoc/dev/best-practices.xml (added)
+++ synapse/branches/2.1/src/site/xdoc/dev/best-practices.xml Fri Dec 23
05:31:34 2011
@@ -0,0 +1,147 @@
+<?xml version="1.0" encoding="ISO-8859-1" ?>
+<!--
+ ~ Licensed to the Apache Software Foundation (ASF) under one
+ ~ or more contributor license agreements. See the NOTICE file
+ ~ distributed with this work for additional information
+ ~ regarding copyright ownership. The ASF licenses this file
+ ~ to you under the Apache License, Version 2.0 (the
+ ~ "License"); you may not use this file except in compliance
+ ~ with the License. You may obtain a copy of the License at
+ ~
+ ~ http://www.apache.org/licenses/LICENSE-2.0
+ ~
+ ~ Unless required by applicable law or agreed to in writing,
+ ~ software distributed under the License is distributed on an
+ ~ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ ~ KIND, either express or implied. See the License for the
+ ~ specific language governing permissions and limitations
+ ~ under the License.
+ -->
+
+<document>
+ <properties>
+ <title>Apache Synapse - Development Best Practices</title>
+ </properties>
+ <body>
+ <section name="Development Best Practices">
+ <p>
+ This document explains the best practices and conventions that
should be followed
+ when writing code, documentation and samples for Apache
Synapse. It is mainly
+ intended for Synapse committers who directly commit code into
the Synapse code base.
+ It is also a useful resource for potential contributors who
are willing to
+ write code for Synapse.
+ </p>
+ <p>
+ Committers are highly encouraged to follow the guidelines
mentioned in this document
+ whenever adding a new source file to the code base or when
modifying an existing source
+ file. Same best practices should be followed when committing a
patch provided by
+ a contributor.
+ </p>
+ <p>
+ This document is a work in progress. We will continue to make
this more detailed
+ and comprehensive as we go along. So stay tuned for updates.
+ </p>
+ <subsection name="Contents">
+ <ul>
+ <li><a href="#Code">Writing Code</a></li>
+ <li><a href="#Docs">Writing Samples and
Documentation</a></li>
+ </ul>
+ </subsection>
+ </section>
+ <section name="Writing Code" id="Code">
+ <ul>
+ <li>
+ We follow the standard
+ <a
href="http://www.oracle.com/technetwork/java/codeconvtoc-136057.html";>Java
coding conventions</a>
+ published by Sun/Oracle. Please stick to these standards
whenever writing code
+ for Synapse.
+ </li>
+ <li>
+ The maximum number of characters in a single line should
not exceed 100. Please
+ configure your IDE to properly enforce this restriction on
all source files.
+ </li>
+ <li>
+ All source files should contain the following license
header at the top.<br/>
+ <div class="xmlConf">/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */</div>
+ </li>
+ <li>
+ Pay attention to indentation and proper spacing between
code blocks.
+ </li>
+ <li>
+ Each Java source file should have a introductory Javadoc
comment describing its
+ main purposes and features.
+ </li>
+ <li>
+ Every public method should have a Javadoc comment
describing its purpose and
+ behavior. When writing Javadoc comments for methods, input
arguments, return
+ values and checked exceptions should also be clearly
explained.
+ </li>
+ <li>
+ Use meaningful names for all classes, interfaces, methods
and variables. Pay
+ attention to spellings. Code should be easier to follow
and understand.
+ </li>
+ <li>
+ Feel free to include comments within the code to explain
non-trivial logic.
+ </li>
+ <li>
+ When removing a public method or an API, first deprecate
the relevant operations
+ by applying the proper Javadoc annotations. Actual removal
of the operation
+ should be done after some time, in a future release.
+ </li>
+ <li>
+ Write test cases for each new feature and bug fix
implemented in the code base.
+ Test cases make it easier to check for regressions and
keep the code base
+ healthy at all times.
+ </li>
+ </ul>
+ </section>
+ <section name="Writing Samples and Documentation" id="Docs">
+ <ul>
+ <li>
+ All documentation files and samples should we well-formed
XML documents.
+ </li>
+ <li>
+ We use the <a
href="http://maven.apache.org/maven-1.x/plugins/xdoc/";>Maven XDoc plugin</a>
+ to generate Synapse documentation and website. Please take
some time to go through
+ the documentation of the XDoc plugin and learn and its
features. In pariculay,
+ you should learn the <a
href="http://maven.apache.org/doxia/references/xdoc-format.html";>XDoc
documentation format</a>
+ and use the standard XDoc tags over HTML whenever possible.
+ </li>
+ <li>
+ Any XML code samples included in the documentation should
be properly HTML
+ encoded and indented. Such code samples should go in a
HTML 'div' section withe
+ the class 'xmlConf'.
+ <div class="xmlConf"><div class="xmlConf">
+ ... Encoded XML content ...
+</div></div>
+ </li>
+ <li>
+ Attempt to keep each line shorter than 100 characters.
This is bit tricky to
+ enforce when writing XML/HTML content. But try to stick to
the rule whenever
+ possible.
+ </li>
+ <li>
+ Add navigation links wherever possible. When describing a
particular feature
+ add a link to the relevant sample.
+ </li>
+ </ul>
+ </section>
+ </body>
+</document>
\ No newline at end of file
Modified: synapse/branches/2.1/src/site/xdoc/userguide/extending.xml
URL:
http://svn.apache.org/viewvc/synapse/branches/2.1/src/site/xdoc/userguide/extending.xml?rev=1222568&r1=1222567&r2=1222568&view=diff
==============================================================================
--- synapse/branches/2.1/src/site/xdoc/userguide/extending.xml (original)
+++ synapse/branches/2.1/src/site/xdoc/userguide/extending.xml Fri Dec 23
05:31:34 2011
@@ -46,12 +46,12 @@
wrapped within a MessageContext
instance, and the message context
is set with the references to
the SynapseConfiguration and
SynapseEnvironment objects. The
- <a
href="apidocs/org/apache/synapse/config/SynapseConfiguration.html">SynapseConfiguration</a>
+ <a
href="../apidocs/org/apache/synapse/config/SynapseConfiguration.html">SynapseConfiguration</a>
object holds the global
configuration model that defines
mediation rules, local registry
entries and other and configuration, while
the
- <a
href="apidocs/org/apache/synapse/core/SynapseEnvironment.html">SynapseEnvironment</a>
+ <a
href="../apidocs/org/apache/synapse/core/SynapseEnvironment.html">SynapseEnvironment</a>
object gives access to the
underlying SOAP implementation used -
Axis2. A typical mediator would
need to manipulate the
Modified: synapse/branches/2.1/src/site/xdoc/userguide/mediators.xml
URL:
http://svn.apache.org/viewvc/synapse/branches/2.1/src/site/xdoc/userguide/mediators.xml?rev=1222568&r1=1222567&r2=1222568&view=diff
==============================================================================
--- synapse/branches/2.1/src/site/xdoc/userguide/mediators.xml (original)
+++ synapse/branches/2.1/src/site/xdoc/userguide/mediators.xml Fri Dec 23
05:31:34 2011
@@ -713,7 +713,7 @@
</p>
<p>
The complete list of available methods can be found in the
- <a
href="apidocs/org/apache/synapse/mediators/bsf/ScriptMessageContext.html">
+ <a
href="../apidocs/org/apache/synapse/mediators/bsf/ScriptMessageContext.html">
ScriptMessageContext Javadoc</a>.
</p>
</subsection>
Modified: synapse/branches/2.1/src/site/xdoc/userguide/transports.xml
URL:
http://svn.apache.org/viewvc/synapse/branches/2.1/src/site/xdoc/userguide/transports.xml?rev=1222568&r1=1222567&r2=1222568&view=diff
==============================================================================
--- synapse/branches/2.1/src/site/xdoc/userguide/transports.xml (original)
+++ synapse/branches/2.1/src/site/xdoc/userguide/transports.xml Fri Dec 23
05:31:34 2011
@@ -366,7 +366,7 @@
hostname of the server matches the names stored inside
the X.509 certificate
presented by the server. Possible values are
<tt>Strict</tt>, <tt>AllowAll</tt>
and <tt>DefaultAndLocalhost</tt>. See the
- <a
href="apidocs/org/apache/synapse/transport/nhttp/HostnameVerifier.html">HostnameVerifier
Javadoc</a>
+ <a
href="../apidocs/org/apache/synapse/transport/nhttp/HostnameVerifier.html">HostnameVerifier
Javadoc</a>
for more details.
</dd>
</dl>
Modified: synapse/branches/2.1/src/site/xdoc/userguide/upgrading.xml
URL:
http://svn.apache.org/viewvc/synapse/branches/2.1/src/site/xdoc/userguide/upgrading.xml?rev=1222568&r1=1222567&r2=1222568&view=diff
==============================================================================
--- synapse/branches/2.1/src/site/xdoc/userguide/upgrading.xml (original)
+++ synapse/branches/2.1/src/site/xdoc/userguide/upgrading.xml Fri Dec 23
05:31:34 2011
@@ -292,7 +292,7 @@
</tr>
<tr class="b">
<td>
- <a
href="apidocs/org/apache/synapse/config/xml/AbstractMediatorFactory.html">AbstractMediatorFactory</a>
+ <a
href="../apidocs/org/apache/synapse/config/xml/AbstractMediatorFactory.html">AbstractMediatorFactory</a>
</td>
<td>createMediator(OMElement)</td>
<td>
@@ -309,7 +309,7 @@
</tr>
<tr class="a">
<td>
- <a
href="apidocs/org/apache/synapse/config/xml/AbstractMediatorSerializer.html">AbstractMediatorSerializer</a>
+ <a
href="../apidocs/org/apache/synapse/config/xml/AbstractMediatorSerializer.html">AbstractMediatorSerializer</a>
</td>
<td>serializeMediator(Mediator)</td>
<td>
@@ -328,7 +328,7 @@
</table>
<p>
Further to that if you have been using
- <a
href="apidocs/org/apache/synapse/ServerManager.html">ServerManager</a>
+ <a
href="../apidocs/org/apache/synapse/ServerManager.html">ServerManager</a>
class you may have noticed that the
class is no more a singleton and doesn't have
the static getInstance method. Also note that the common
utilities like data
sources JMX and RMI registration stuff have been moved to
a new module with
@@ -339,9 +339,9 @@
construct its instance and that has been used to pass in
any additional information
required like RESOLVE_ROOT, or SYNAPSE_HOME startup
parameters. For example if you
look at the
- <a
href="apidocs/org/apache/synapse/config/xml/MediatorFactoryFinder.html">MediatorFactoryFinder</a>
+ <a
href="../apidocs/org/apache/synapse/config/xml/MediatorFactoryFinder.html">MediatorFactoryFinder</a>
class the
- <a
href="apidocs/org/apache/synapse/config/xml/MediatorFactoryFinder.html#getMediator(org.apache.axiom.om.OMElement,%20java.util.Properties)">getMediator</a>
+ <a
href="../apidocs/org/apache/synapse/config/xml/MediatorFactoryFinder.html#getMediator(org.apache.axiom.om.OMElement,%20java.util.Properties)">getMediator</a>
method is expecting a properties map
apart from the OMElement argument.
It is safe to pass in a empty
properties map if you are using these methods for
any testing purposes or even in cases where you do not
resolve dependencies.
