You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@synapse.apache.org by hi...@apache.org on 2011/12/22 20:47:17 UTC
svn commit: r1222410 - in /synapse/branches/2.1/src/site: site.xml xdoc/dev/
xdoc/dev/developer-guide.xml xdoc/developer-guide.xml
Author: hiranya
Date: Thu Dec 22 19:47:16 2011
New Revision: 1222410
URL: http://svn.apache.org/viewvc?rev=1222410&view=rev
Log:
Added dev folder for developer resources
Added:
synapse/branches/2.1/src/site/xdoc/dev/
synapse/branches/2.1/src/site/xdoc/dev/developer-guide.xml
- copied, changed from r1222320, synapse/branches/2.1/src/site/xdoc/developer-guide.xml
Removed:
synapse/branches/2.1/src/site/xdoc/developer-guide.xml
Modified:
synapse/branches/2.1/src/site/site.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=1222410&r1=1222409&r2=1222410&view=diff
==============================================================================
--- synapse/branches/2.1/src/site/site.xml (original)
+++ synapse/branches/2.1/src/site/site.xml Thu Dec 22 19:47:16 2011
@@ -50,8 +50,8 @@
<item name="FAQ" href="userguide/faq.html"/>
</menu>
<menu name="Developer Resources">
- <item name="Developer Guide " href="developer-guide.html"/>
- <item name="Developer Guidelines"/>
+ <item name="Developer Guide " href="dev/developer-guide.html"/>
+ <item name="Developer Best Practices"/>
<item name="Release Process"/>
<item name="How to Contribute"/>
</menu>
Copied: synapse/branches/2.1/src/site/xdoc/dev/developer-guide.xml (from r1222320, synapse/branches/2.1/src/site/xdoc/developer-guide.xml)
URL: http://svn.apache.org/viewvc/synapse/branches/2.1/src/site/xdoc/dev/developer-guide.xml?p2=synapse/branches/2.1/src/site/xdoc/dev/developer-guide.xml&p1=synapse/branches/2.1/src/site/xdoc/developer-guide.xml&r1=1222320&r2=1222410&rev=1222410&view=diff
==============================================================================
--- synapse/branches/2.1/src/site/xdoc/developer-guide.xml (original)
+++ synapse/branches/2.1/src/site/xdoc/dev/developer-guide.xml Thu Dec 22 19:47:16 2011
@@ -23,109 +23,247 @@
<title>Apache Synapse - Developer Guide</title>
</properties>
<body>
- <section name="Apache Synapse Development Guide">
+ <section name="Developer Guide">
<p>
- Welcome to Apache Synapse Developer Guide. This guide have following contents,
+ Welcome to Apache Synapse Developer Guide. This document is a starting point for
+ anyone who's willing to write code for Synapse and make contributions. We welcome
+ several different types of contributions such as ideas, new features, bug fixes,
+ documentation and samples. This guide strives to provide information on how you can
+ get the Synapse source code, how to setup the development environment and how to
+ make contributions. Further it provides instructions on how to get in touch with the
+ other developers, how to report issues and how to keep track of development activities.
</p>
+ <p>
+ If you are an experienced Synapse developer or already a committer
+ for Synapse, this document might still contain useful information on setting up
+ your working copy of the source code and committing code changes. So feel free to
+ read all the way through.
+ </p>
+ </section>
+ <section name="Contents">
<ul>
<li>
- <a href="#intro">Introduction</a>
+ <a href="#subversion">Interacting with the Code Base Using Subversion</a>
+ <ul>
+ <li><a href="#checkout">Checking Out the Source</a></li>
+ </ul>
</li>
<li>
- <a href="#subversion">Using Subversion (SVN)</a>
+ <a href="#maven">Interacting with the Build System Using Apache Maven</a>
+ <ul>
+ <li><a href="#building">Building from Source</a></li>
+ <li><a href="#environment">Setting Up the Development Environment</a></li>
+ <li><a href="#integration">Integration Tests</a></li>
+ <li><a href="#testdebug">Debugging Tests</a></li>
+ </ul>
</li>
<li>
- <a href="#checkout">Checking Out Synapse Codebase</a>
+ <a href="#debug">Debugging the Synapse Server</a>
</li>
<li>
- <a href="#maven2">Installing Maven 2</a>
+ <a href="#issues">Reporting Issues</a>
</li>
<li>
- <a href="#config_ide">Configuring your IDE</a>
+ <a href="#contrib">Making Contributions</a>
</li>
</ul>
</section>
-
- <section name="Introduction" id="intro">
- <p>This document provides information on how to use Subversion(SVN) to checkout/update/commits
- to codebase, etc, in persepective of contributing to Apache Synapse. We have described
- Instructions on configuring IDEs for development and using Maven as build and project
- management tool .
- </p>
- </section>
- <section name="Using Subversion (SVN)" id="subversion">
- <p> Synapse uses Subversion (SVN) for source control. Subversion has been the popular
- versioning system preferred over CVS . It is also licensed under a Apache compatible
- license.
- To learn more about Subversion or to download the latest distribution, visit the
- <a class="externalLink" href="http:///subversion.tigris.org">Subversion project
- site</a>. A guide on setting up and installing Subversion, is available at ASF
- <a class="externalLink" href="http://www.apache.org/dev/version-control.html"/> Source
- Code Repositories page</p>
- </section>
- <section name="Checking Out Synapse Codebase" id="checkout">
- <p>To check out the latest version of Synapse from project SVN repository, you must use
- one of the following URLs depending on your level of access to the Synapse source code:
- ie:- a committer or non committer</p>
-
- <ul>
- <li><b>If you are not a committer:</b> <a class="externalLink" href="http://svn.apache.org/repos/asf/synapse/trunk/java/">http://svn.apache.org/repos/asf/synapse/trunk/java/</a></li>
-
- <li><b>If you are a committer:</b> <a class="externalLink" href="https://svn.apache.org/repos/asf/synapse/trunk/java/">https://svn.apache.org/repos/asf/synapse/trunk/java/</a></li>
- </ul>
+ <section name="Interacting with the Code Base Using Subversion" id="subversion">
+ <p>
+ Synapse code base is maintained in a Subversion repository. Therefore anybody willing
+ to go through the Synapse source code in the development trunk and make contributions
+ should use a Subversion client to interact with the Synapse code base. To learn more
+ about using Subversion or to download the latest client distributions, please visit
+ the <a href="http://subversion.apache.org">Apache Subversion project website</a>.
+ Developers on Unix/Linux based systems may use the command line based SVN client,
+ while the developers on Windows platform can use an appropriate client application
+ like <a href="http://tortoisesvn.net/">TortoiseSVN</a>.
+ </p>
+ <p>
+ Some useful information on using the Apache Software Foundation's source code
+ repositories can be found among the ASF
+ <a href="http://www.apache.org/dev/version-control.html">developer documentation</a>.
+ </p>
+ <subsection name="Checking Out the Source" id="checkout">
+ <p>
+ Synapse development trunk is where all the latest development work takes place.
+ This is located at
+ <a href="http://svn.apache.org/repos/asf/synapse/trunk/java/">http://svn.apache.org/repos/asf/synapse/trunk/java/</a>.
+ Any developer with a Subversion client should be able to checkout the latest
+ source from this SVN location but only Synapse committers are allowed to actually
+ commit source code. Synapse committers should access the above SVN location over
+ HTTPS and provide the ASF committer credentials to checkout and commit source
+ code. Please refer the <a href="../source-repository.html">source repository guide</a>
+ for more details on checking out the source code from the above repository.
+ </p>
+ <p>
+ Once you have checked out the source code, you can update your working copy by
+ running the 'svn update' command. This will checkout the modifications since the
+ last checkout/update and bring your local working copy to the latest revision.
+ </p>
+ <p>
+ If you want to browse the source code of an older release of Synapse or want
+ to implement a patch for a past release, you may checkout the relevant source
+ tree from one of the available SVN
+ <a href="http://svn.apache.org/repos/asf/synapse/tags/">tags</a>.
+ </p>
+ </subsection>
+ </section>
+ <section name="Interacting with the Build System Using Apache Maven" id="maven">
+ <p>
+ Synapse build system is based on Apache Maven. Either Maven2 or Maven3 can be used to
+ build Apache Synapse from source. For information about downloading, installing, and
+ configuring Maven, please go through
+ <a class="externalLink" href="http://maven.apache.org">Maven project website</a>.
+ </p>
+ <subsection name="Building from Source" id="building">
+ <p>
+ To build all the modules and the Synapse binary distribution, go to
+ the root of the Synapse source tree and execute the following Maven command.
+ </p>
+ <div class="command">mvn clean install</div>
+ <p>
+ This will fetch all the required dependencies, compile the source, run the tests
+ and build the Synapse modules and the binary pack. Please note that building
+ with tests takes time. To build without the tests, use the following Maven
+ command.
+ </p>
+ <div class="command">mvn clean install -Dmaven.test.skip=true</div>
+ <p>
+ Developers and committers making changes to the Synapse code base are highly
+ recommended to always build the source 'WITH' the tests. This will ensure that
+ changes do not introduce any obvious regression errors. However running all the
+ tests does not guarantee that a particular change will not introduce any
+ regressions. Therefore care must be exercised whenever making changes to the
+ existing code.
+ </p>
+ <p>
+ Synapse source tree is organized into several modules. If required you can build
+ only a selected module by going into the appropriate module and executing one
+ of the above build commands.
+ </p>
+ </subsection>
+ <subsection name="Setting Up the Development Environment" id="environment">
+ <p>
+ Apache Synapse development can be based on a number of tools ranging from simple
+ command line tools like Vim and Emacs to full fledged Java IDEs like Eclipse,
+ IntelliJ Idea and Netbeans. If Eclipse or Idea is used to develop code for
+ Synapse, Maven can be used to build the necessary project artifacts.
+ </p>
+ <p>
+ Simply run the following commands to generate the project artifacts and then
+ use your IDE to open up the Synapse code base as a Java project.
+ </p>
+ <div class="command">For Idea: mvn idea:idea
+For Eclipse: mvn eclipse:eclipse</div>
+ </subsection>
+ <subsection name="Integration Tests" id="integration">
+ <p>
+ Starting from Synapse 2.1, a suite of integration tests are included in the
+ Synapse code base. These tests automate various samples included in the Synapse
+ binary distribution and provide a convenient way to sanity check a Synapse
+ distribution and find any regressions. If you build the source tree from the root
+ without skipping the test cases, these integration tests will be executed by
+ Maven as a part of the build process. If you just need to run the integration
+ tests simply go into the modules/integration directory in the source tree and
+ run the usual Maven build command.
+ </p>
+ <p>
+ Synapse integration test suite uses the Maven Surefire plugin. Therefore all
+ tests will generate a report which will be available in the
+ modules/integration/target/surefire-reports directory. If you ever encounter
+ a failure while running the integration tests, this is the first place to check.
+ </p>
+ <p>
+ You can pass additional parameters to the Synapse integration test framework and
+ limit the number of tests executed by Maven. For an example if you simply want
+ to run sample 10 in the integration test framework, run the following command.
+ </p>
+ <div class="command">mvn clean install -Dtests=10</div>
+ <p>
+ You can also run a list of known samples as an integration test.
+ </p>
+ <div class="command">mvn clean install -Dtests=10,11,12</div>
+ <p>
+ Synapse samples are categorized into several sections. If needed you can run all
+ the samples in a particular section.
+ </p>
+ <div class="command">mvn clean install -Dsuite=proxy</div>
+ <div class="command">mvn clean install -Dsuite=endpoint</div>
+ <p>
+ Following values can be passed in as the value of the 'suite' parameter.
+ </p>
+ <ul>
+ <li>message</li>
+ <li>endpoint</li>
+ <li>qos</li>
+ <li>proxy</li>
+ <li>tasks</li>
+ <li>advanced</li>
+ </ul>
+ </subsection>
+ <subsection name="Debugging Tests" id="testdebug">
+ <p>
+ Maven allows you to remote debug tests at build time. To make use of this
+ feature simply run the Maven build command with the -Dmaven.surefire.debug
+ flag.
+ </p>
+ <div class="command">mvn clean install -Dmaven.surefire.debug</div>
+ <p>
+ This will open up port 5005 for remote debugging and you can use your IDE to
+ connect to that port and remote debug the test source (or even Synapse source).
+ </p>
+ </subsection>
+ </section>
+ <section name="Debugging the Synapse Server" id="debug">
+ <p>
+ If you are running the Synapse binary distribution and wants to debug the server
+ to fix some issue, simply start the server with the -xdebug option.
+ </p>
+ <div class="command">sh synapse.sh -xdebug</div>
+ <p>
+ This will open up port 8000 for remote debugging. Now you can connect to the server
+ from your IDE and remote debug it against the source code. If you want to debug a
+ message flow in Synapse, it's recommended to place some break points in the
+ org.apache.synapse.core.axis2.SynapseMessageReceiver and org.apache.synapse.core.axis2.ProxyServiceMessageReceiver
+ classes.
+ </p>
+ </section>
+ <section name="Reporting Issues" id="issues">
+ <p>
+ Please report all issues in the <a href="../issue-tracking.html">Synapse JIRA</a>.
+ You can also create JIRA issues for any suggestions, improvements and new features
+ you have in mind. If you wish to further discuss some idea with the rest of the
+ Synapse community, please write to the appropriate <a href="../mail-lists.html">mailing lists</a>.
+ </p>
+ <p>
+ You are also encouraged to comment on other issues in the Synapse JIRA, ask questions
+ and if possible make code/documentation contributions.
+ </p>
+ </section>
+ <section name="Making Contributions" id="contrib">
<p>
- If you are a committer,you have to have a svn password at hand. To get more info
- on credentials you must log into svn.apache.org. Please read the ASF
- <a class="externalLink" href="http://www.apache.org/dev/version-control.html">
- Source Code Repositories page</a>.
- </p>
- <p>
- Use following commands to manage Synapse code at subversion :
- </p>
- <ol>
- <li>Run <b>svn co <repository URL> synapse</b> where
- the repository URL is one of the URLs from the previous list.</li>
- <li>To update your working copy to the latest version ,execute the <b>svn update</b>
- or <b>svn up</b>command.</li>
- <li>to submit a patch, execute <b>svn diff</b> to create a unified diff for
- submission to the SYNAPSE JIRA issue tracker.</li>
- </ol>
- </section>
- <section name="Installing Maven 2" id="maven2">
- <p>
- Synapse build is based on Maven 2. For information about downloading, installing, and
- configuring Maven 2, please go through <a class="externalLink"
- href="http://maven.apache.org">Maven project
- page</a>.
- To use Maven to build the Synapse project, Please install
- <a class="externalLink" href="http://maven.apache.org/download.html">Maven2</a>
- </p>
- <p>
- Use following commands to build from Synapse source code using maven2 :
- </p>
- <ol>
- <li>Go to top level synapse folder Run <b>mvn clean install </b>. This will build all
- synapse modules from the top. Maven will use online repositories . You can build from
- individual modules as well. Go to module/{module_name} and run the above command</li>
-
- <li>To build Synapse offline use -o option ie:- <b>mvn clean install -o </b> </li>
- <li>To build Synapse without tests use <b>mvn clean install -Dmaven.test.skip=true
- </b> </li>
- </ol>
-
- </section>
- <section name="Configuring your IDE" id="config_ide">
- <p>The Synapse development can be based on variety of development tools
- from vim, emacs, Netbeans to Eclipse to Intellij/IDEA. Having said that we recommend
- users to use Eclipse or IDEA and there's direct development support for these IDE's
- from maven2.</p>
-
- <p> Type <b>mvn idea:idea</b>. Generates the necessary IDEA .ipr, .iml and .iws project
- files. </p>
-
- <p>Type <b>mvn eclipse:eclipse</b>. Generates the necessary eclipse project files. </p>
+ If you have implemented a new feature, fixed some bug in the code or written a new
+ sample, we'll be more than happy to review it and include it in the Synapse code
+ base for everyone's benefit. If you are interested in contributing your work to Synapse,
+ please create an issue in the JIRA system first. Then you can attach your workings to
+ the JIRA issue as a patch.
+ </p>
+ <p>
+ To create a patch file out of your work simply run the 'svn diff' command.
+ </p>
+ <div class="command">svn diff > FixForIssue123.patch</div>
+ <p>
+ If you added any new files as a part of your work you should first run the 'svn add'
+ command on them before creating the patch file. Otherwise they won't be included
+ in the generated patch.
+ </p>
+ <p>
+ Once the patch file has been created, attach it to the relevant JIRA issue and make
+ sure to grant the ASF permission to use your patch in ASF development activities.
+ One of the committers will review your work and provide feedback through the JIRA. If
+ all is well, the patch will eventually go into the Synapse development trunk.
+ </p>
</section>
-
-
</body>
</document>
\ No newline at end of file