You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@tapestry.apache.org by bu...@apache.org on 2014/02/08 16:20:40 UTC
svn commit: r896900 - in /websites/production/tapestry/content:
cache/main.pageCache community.html developer-bible.html
developer-information.html
Author: buildbot
Date: Sat Feb 8 15:20:40 2014
New Revision: 896900
Log:
Production update by buildbot for tapestry
Modified:
websites/production/tapestry/content/cache/main.pageCache
websites/production/tapestry/content/community.html
websites/production/tapestry/content/developer-bible.html
websites/production/tapestry/content/developer-information.html
Modified: websites/production/tapestry/content/cache/main.pageCache
==============================================================================
Binary files - no diff available.
Modified: websites/production/tapestry/content/community.html
==============================================================================
--- websites/production/tapestry/content/community.html (original)
+++ websites/production/tapestry/content/community.html Sat Feb 8 15:20:40 2014
@@ -62,11 +62,11 @@
<div id="content">
<div id="ConfluenceContent"><p>Tapestry has an active community of users and developers. This is an overview of how to participate, along with a list of some of the great contributions of the community members.</p><p><style type="text/css">/*<![CDATA[*/
-div.rbtoc1390321244989 {padding: 0px;}
-div.rbtoc1390321244989 ul {list-style: disc;margin-left: 0px;}
-div.rbtoc1390321244989 li {margin-left: 0px;padding-left: 0px;}
+div.rbtoc1391872833144 {padding: 0px;}
+div.rbtoc1391872833144 ul {list-style: disc;margin-left: 0px;}
+div.rbtoc1391872833144 li {margin-left: 0px;padding-left: 0px;}
-/*]]>*/</style></p><div class="toc-macro rbtoc1390321244989">
+/*]]>*/</style></p><div class="toc-macro rbtoc1391872833144">
<ul class="toc-indentation"><li><a shape="rect" href="#Community-GettingInvolved">Getting Involved</a>
<ul class="toc-indentation"><li><a shape="rect" href="#Community-ReportingProblems/GettingSupport">Reporting Problems / Getting Support</a></li><li><a shape="rect" href="#Community-ContributingtranslationsforTapestrybuilt-inmessages">Contributing translations for Tapestry built-in messages</a></li><li><a shape="rect" href="#Community-SourceCodeAccess">Source Code Access</a></li><li><a shape="rect" href="#Community-BecomingaContributor">Becoming a Contributor</a></li><li><a shape="rect" href="#Community-BecomingaCommitter">Becoming a Committer</a></li></ul>
</li><li><a shape="rect" href="#Community-CommunityContributions">Community Contributions</a>
@@ -79,7 +79,7 @@ div.rbtoc1390321244989 li {margin-left:
<div class="table-wrap"><table class="confluenceTable"><tbody><tr><td colspan="1" rowspan="1" class="confluenceTd"><p> </p></td><th colspan="1" rowspan="1" class="confluenceTh"><p> Subscribe </p></th><th colspan="1" rowspan="1" class="confluenceTh"><p> Unsubscribe </p></th><th colspan="1" rowspan="1" class="confluenceTh"><p> Apache Archive </p></th><th colspan="1" rowspan="1" class="confluenceTh"><p> Nabble Archive </p></th><th colspan="1" rowspan="1" class="confluenceTh"><p> MarkMail Archive </p></th></tr><tr><th colspan="1" rowspan="1" class="confluenceTh"><p> Tapestry User List </p></th><td colspan="1" rowspan="1" class="confluenceTd"><p> <a shape="rect" class="external-link" href="mailto:users-subscribe@tapestry.apache.org" >Subscribe</a> </p></td><td colspan="1" rowspan="1" class="confluenceTd"><p> <a shape="rect" class="external-link" href="mailto:users-unsubscribe@tapestry.apache.org" >Unsubscribe</a> </p></td><td colspan="1" rowspan="1" class="confluenceTd"><p> <a shape
="rect" class="external-link" href="http://mail-archives.apache.org/mod_mbox/tapestry-users/">mail-archives.apache.org</a> </p></td><td colspan="1" rowspan="1" class="confluenceTd"><p> <a shape="rect" class="external-link" href="http://tapestry.1045711.n5.nabble.com/Tapestry-User-f2375125.html" >www.nabble.com</a> </p></td><td colspan="1" rowspan="1" class="confluenceTd"><p> <a shape="rect" class="external-link" href="http://tapestry.markmail.org/search/?q=list%3Aorg.apache.tapestry.users" >tapestry.markmail.org</a> </p></td></tr><tr><th colspan="1" rowspan="1" class="confluenceTh"><p> Tapestry Developer List </p></th><td colspan="1" rowspan="1" class="confluenceTd"><p> <a shape="rect" class="external-link" href="mailto:dev-subscribe@tapestry.apache.org" >Subscribe</a> </p></td><td colspan="1" rowspan="1" class="confluenceTd"><p> <a shape="rect" class="external-link" href="mailto:dev-unsubscribe@tapestry.apache.org" >Unsubscribe</a> </p></td><td colspan="1" rowspan="1" class="conflu
enceTd"><p> <a shape="rect" class="external-link" href="http://mail-archives.apache.org/mod_mbox/tapestry-dev/">mail-archives.apache.org</a> </p></td><td colspan="1" rowspan="1" class="confluenceTd"><p> <a shape="rect" class="external-link" href="http://tapestry.1045711.n5.nabble.com/Tapestry-Dev-f2438278.html" >www.nabble.com</a> </p></td><td colspan="1" rowspan="1" class="confluenceTd"><p> <a shape="rect" class="external-link" href="http://tapestry.markmail.org/search/?q=list%3Aorg.apache.tapestry.dev" >tapestry.markmail.org</a> </p></td></tr><tr><th colspan="1" rowspan="1" class="confluenceTh"><p> Tapestry Commits List </p></th><td colspan="1" rowspan="1" class="confluenceTd"><p> <a shape="rect" class="external-link" href="mailto:commits-subscribe@tapestry.apache.org" >Subscribe</a> </p></td><td colspan="1" rowspan="1" class="confluenceTd"><p> <a shape="rect" class="external-link" href="mailto:commits-unsubscribe@tapestry.apache.org" >Unsubscribe</a> </p></td><td colspan="1" rows
pan="1" class="confluenceTd"><p> <a shape="rect" class="external-link" href="http://mail-archives.apache.org/mod_mbox/tapestry-commits/">mail-archives.apache.org</a> </p></td><td colspan="1" rowspan="1" class="confluenceTd"><p> - </p></td><td colspan="1" rowspan="1" class="confluenceTd"><p> <a shape="rect" class="external-link" href="http://tapestry.markmail.org/search/?q=list%3Aorg.apache.tapestry.commits" >tapestry.markmail.org</a> </p></td></tr><tr><th colspan="1" rowspan="1" class="confluenceTh"><p> Search Multiple Lists </p></th><td colspan="1" rowspan="1" class="confluenceTd"><p> - </p></td><td colspan="1" rowspan="1" class="confluenceTd"><p> - </p></td><td colspan="1" rowspan="1" class="confluenceTd"><p> - </p></td><td colspan="1" rowspan="1" class="confluenceTd"><p> <a shape="rect" class="external-link" href="http://tapestry.1045711.n5.nabble.com/" >www.nabble.com</a> </p></td><td colspan="1" rowspan="1" class="confluenceTd"><p> <a shape="rect" class="external-link" href="ht
tp://tapestry.markmail.org/search/?q=#query:+page:1+state:facets" >tapestry.markmail.org</a> </p></td></tr></tbody></table></div><p>Tapestry issues are tracked in the <a shape="rect" class="external-link" href="https://issues.apache.org/jira/browse/TAP5">Apache JIRA</a>.</p><p>Unless your problem is clear as day, it's a good idea to discuss it on the Tapestry Users mailing list first, before adding an issue. At the same time, it's generally unlikely that a bug will be fixed <em>unless</em> a JIRA Issue is created.</p><p>Eric Raymond has a detailed <a shape="rect" class="external-link" href="http://catb.org/esr/faqs/smart-questions.html" >guide to asking questions the right way</a>. If you are not getting a response to your problem, it's likely because you aren't asking it the right way.</p><p>Just saying something is "broken" or "failed" is not enough. How did it fail? Did it do the wrong thing? Throw an exception? Not respond in any way? What exactly did you expect to happen? All o
f this information should be made available when looking for help, plus context on the general problem you were trying to solve in the first place (there may be a better solution entirely). Read Eric Raymond's guide ... it's fun and informative.</p><h2 id="Community-ContributingtranslationsforTapestrybuilt-inmessages">Contributing translations for Tapestry built-in messages</h2><p>If Tapestry's built-in messages aren't available in your language, you are welcome to contribute a new translation of the message catalogs. For easy instructions, see <a shape="rect" href="localization.html#Localization-ProvidingtranslationsforTapestrybuiltinmessages">Localization</a>.</p><h2 id="Community-SourceCodeAccess">Source Code Access</h2><p>Source code for Tapestry can be <a shape="rect" href="download.html">downloaded</a> along with pre-compiled binaries.</p><p>Tapestry uses <a shape="rect" class="external-link" href="http://git-scm.com/" >Git</a> to manage the project's source code.</p><p>Web ac
cess to the Tapestry repository is available as <a shape="rect" class="external-link" href="https://git-wip-us.apache.org/repos/asf?p=tapestry-5.git">GIT-WIP at Apache</a>.</p><p>Access using Git client:</p><div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
<pre>$ git clone http://git-wip-us.apache.org/repos/asf/tapestry-5.git
</pre>
-</div></div><p>(See <a shape="rect" href="building-tapestry-from-source.html">Building Tapestry from Source</a> for more info.)</p><h2 id="Community-BecomingaContributor">Becoming a Contributor</h2><p>The best way to become a contributor is to become active on the mailing list; Tapestry is known to have an active and helpful community on the mailing list, and the more mentors we can add, the better.</p><p>If you want to help out with documentation, you must sign an <a shape="rect" class="external-link" href="http://www.apache.org/licenses/#clas">Apache Contributor License Agreement</a>, at which point we can grant write access to the Confluence Wiki (where official documentation is created).</p><p>Providing patches (with tests!) is another way to become a contributor.</p><h2 id="Community-BecomingaCommitter">Becoming a Committer</h2><p>Active contributors may be asked to become full committers, with write access to the source code. Generally, contributors who have been consistently
active and helpful for three to six months are eligible for committer access. If you think you are in that category, don't be shy about contacting members of the Tapestry PMC (Project Management Committee).</p><hr><h1 id="Community-CommunityContributions">Community Contributions</h1><div class="sectionColumnWrapper"><div class="sectionMacro"><div class="sectionMacroRow"><div class="columnMacro" style="width:50%;min-width:50%;max-width:50%;"><p><span class="confluence-anchor-link" id="Community-modules"></span></p><p> </p><div id="third-parties"><p> </p><h2 id="Community-Modules">Modules</h2><p><a shape="rect" class="external-link" href="https://github.com/chenillekit/chenillekit" >Chenille Kit</a> by Massimo Lusetti</p><blockquote><p>Collection of modules, services, utilities and components (many of which require only tapestry-ioc). Includes Accordion, ColorPicker, Editor, Kaptcha, MultipleSelect, RoundCornerContainer, ThumbNail, and many more useful components. Also provi
des integrations with Google services, LDAP, Lucene, Mail, Quartz, JasperReports, Bean Scripting Framework, and more.</p></blockquote><p><a shape="rect" class="external-link" href="http://equanda.org/equanda-tapestry5/" >Equanda-tapestry5</a> by Joachim Van der Auwera</p><blockquote><p>Components useful for building enterprise applications. Includes Accordion, Form Traversal, Tabs, TextAreaAutoExpander, TreeTable, . Among other things, these focus on easy input of data without the need for a mouse.</p></blockquote><p><a shape="rect" class="external-link" href="http://tapestry.ioko.com/" >ioko-tapestry-commons</a> by Ben Gidley, et al.</p><blockquote><p>Provides components for caching, cache control, and simple Flash movie integration.</p></blockquote><p><a shape="rect" class="external-link" href="http://tapestry.formos.com/nightly/tapx/" >Tapx</a> by Howard M. Lewis Ship</p><blockquote><p>Collection of modules and components: improved DatePicker, dynamic Tapestry templates, offline
rendering using Tapestry, YUI integration, Confirm dialog mixin, Kaptcha components, and more!</p></blockquote><p><a shape="rect" class="external-link" href="http://tapestry5-jquery.com/" >Tapestry5-jQuery</a> by GOT5</p><blockquote><p>Tapestry5-Jquery lets you use jQuery to completely replace Prototype, Scriptaculous and the base tapestry.js script.</p></blockquote><p><a shape="rect" class="external-link" href="http://exanpe-t5-lib.appspot.com/" >Exanpe-T5-Lib</a> by Laurent Guérin et Julien Maupoux</p><blockquote><p>A library of components: accordion, ajax loader, slider, tab view, secured password, color picker, tooltip, hideable panel and more! Live demo is provided.</p></blockquote><p><a shape="rect" class="external-link" href="http://code.google.com/p/flowlogix/" >FlowLogix</a> by Lenny Primak</p><blockquote><p>a collection of components, services and utilities that integrates Tapestry into JEE environments and provides other commonly needed functionality.</p></blockquote
><p><a shape="rect" href="modules.html">More Modules</a>...</p><h1 id="Community-Extensions">Extensions</h1><p><a shape="rect" class="external-link" href="http://www.arsmachina.com.br/" >Ars Machina</a> by Thiago H. de Paula Figueiredo</p><blockquote><p>Tapestry/Hibernate extensions for Generic DAOs, standard CRUD interfaces, and user access logging and tracking.</p></blockquote><p><a shape="rect" class="external-link" href="http://tynamo.org/" >Tynamo project</a> by Tynamo Team / Kalle Korhonen & Alejandro Scandroli</p><blockquote><p>Tynamo is model-driven, full-stack web framework based on Tapestry 5, allowing you to jump directly from your Hibernate entities to a full-blown CRUD application. Tynamo provides several modules, including tapestry-model, tapestry-conversations, tapestry-hibernate-seedentity, tapestry-resteasy and tapestry-security.</p></blockquote></div><div class="columnMacro"><h1 id="Community-Tutorials">Tutorials</h1><p><a shape="rect" class="external-link" hre
f="http://jumpstart.doublenegative.com.au/jumpstart" >Tapestry JumpStart</a> by Geoff Callender</p><blockquote><p>JumpStart is an easy way to learn Tapestry by example. It's an online demo application, and also a downloadable open source app ready for you to explore and modify.</p></blockquote><p><a shape="rect" class="external-link" href="http://tapestry-stitch.uklance.cloudbees.net/" >Tapestry Stitch</a> by Lance</p><blockquote><p>Sample components and concepts in Apache Tapestry 5</p></blockquote><p><a shape="rect" class="external-link" href="http://code.google.com/p/shams/" >Shams Examples</a> by Mohammad H. Shamsi</p><blockquote><p>A variety of examples of Tapestry 5 pages and components.</p></blockquote><p><a shape="rect" class="external-link" href="http://wiki.apache.org/tapestry/FrontPage">Community's Wiki</a> (Moin Moin)</p><blockquote><p>The wiki contains a wealth of user-generated tips and techniques for using Tapestry</p></blockquote><h1 id="Community-IDEIntegrations">ID
E Integrations</h1><p><a shape="rect" class="external-link" href="https://github.com/anjlab/eclipse-tapestry5-plugin" >Eclipse-tapestry5-plugin</a></p><blockquote><p>An Eclipse plugin for Tapestry 5 by Dmitry Gusev, with a "Quick Switch" between templates and component classes, a Tapestry Context view, and many other convenience features. <span style="color: rgb(112,112,112);">This is currently the best choice for Eclipse users.</span></p></blockquote><p><a shape="rect" class="external-link" href="http://code.google.com/p/tapestrytools/wiki/Install_Guide_Lightweight_TapestryTools" >Tapestry Tools</a> by Gavin Lei</p><blockquote><p>Tapestry Tools is an Eclipse plugin for Tapestry 5 which has been built by Gavin Lei within the timeframe of GSoC 2012.</p></blockquote><p><a shape="rect" class="external-link" href="http://www.jetbrains.com/idea" >IntelliJ 10</a> by JetBrains</p><blockquote><p>IntelliJ has Tapestry 5 support included <a shape="rect" class="external-link" href="http://www.
jetbrains.com/idea/features/tapestry_5.html" >right out of the box</a>.</p></blockquote><p><a shape="rect" class="external-link" href="http://code.google.com/p/loom-t5/" >loom-t5</a> by Chris Scheid</p><blockquote><p>Eclipse plugin for building Tapestry 5 projects</p></blockquote><p><a shape="rect" class="external-link" href="http://wiki.apache.org/tapestry/Tapestry5JSPEditorEclipse">Code Completion in Eclipse</a></p><blockquote><p>How to use the built in JSP Eclipse Editor and a custom tld file to get Tapestry 5 code completion in Eclipse</p></blockquote></div></div></div></div></div></div>
+</div></div><p>(See <a shape="rect" href="building-tapestry-from-source.html">Building Tapestry from Source</a> for more info.)</p><h2 id="Community-BecomingaContributor">Becoming a Contributor</h2><p>The best way to become a contributor is to become active on the mailing list; Tapestry is known to have an active and helpful community on the mailing list, and the more mentors we can add, the better.</p><p>If you want to help out with documentation, you must sign an <a shape="rect" class="external-link" href="http://www.apache.org/licenses/#clas">Apache Contributor License Agreement</a>, at which point we can grant write access to the Confluence Wiki (where official documentation is created).</p><p>Providing patches (with tests!) is another way to become a contributor. (See the <a shape="rect" href="developer-bible.html">Developer Bible</a> for important guidance on source code formatting, class naming conventions, etc.)</p><h2 id="Community-BecomingaCommitter">Becoming a Commit
ter</h2><p>Active contributors may be asked to become full committers, with write access to the source code. Generally, contributors who have been consistently active and helpful for three to six months are eligible for committer access. If you think you are in that category, don't be shy about contacting members of the Tapestry PMC (Project Management Committee).</p><hr><h1 id="Community-CommunityContributions">Community Contributions</h1><div class="sectionColumnWrapper"><div class="sectionMacro"><div class="sectionMacroRow"><div class="columnMacro" style="width:50%;min-width:50%;max-width:50%;"><p><span class="confluence-anchor-link" id="Community-modules"></span></p><p> </p><div id="third-parties"><p> </p><h2 id="Community-Modules">Modules</h2><p><a shape="rect" class="external-link" href="https://github.com/chenillekit/chenillekit" >Chenille Kit</a> by Massimo Lusetti</p><blockquote><p>Collection of modules, services, utilities and components (many of which require on
ly tapestry-ioc). Includes Accordion, ColorPicker, Editor, Kaptcha, MultipleSelect, RoundCornerContainer, ThumbNail, and many more useful components. Also provides integrations with Google services, LDAP, Lucene, Mail, Quartz, JasperReports, Bean Scripting Framework, and more.</p></blockquote><p><a shape="rect" class="external-link" href="http://equanda.org/equanda-tapestry5/" >Equanda-tapestry5</a> by Joachim Van der Auwera</p><blockquote><p>Components useful for building enterprise applications. Includes Accordion, Form Traversal, Tabs, TextAreaAutoExpander, TreeTable, . Among other things, these focus on easy input of data without the need for a mouse.</p></blockquote><p><a shape="rect" class="external-link" href="http://tapestry.ioko.com/" >ioko-tapestry-commons</a> by Ben Gidley, et al.</p><blockquote><p>Provides components for caching, cache control, and simple Flash movie integration.</p></blockquote><p><a shape="rect" class="external-link" href="http://tapestry.formos.com/ni
ghtly/tapx/" >Tapx</a> by Howard M. Lewis Ship</p><blockquote><p>Collection of modules and components: improved DatePicker, dynamic Tapestry templates, offline rendering using Tapestry, YUI integration, Confirm dialog mixin, Kaptcha components, and more!</p></blockquote><p><a shape="rect" class="external-link" href="http://tapestry5-jquery.com/" >Tapestry5-jQuery</a> by GOT5</p><blockquote><p>Tapestry5-Jquery lets you use jQuery to completely replace Prototype, Scriptaculous and the base tapestry.js script.</p></blockquote><p><a shape="rect" class="external-link" href="http://exanpe-t5-lib.appspot.com/" >Exanpe-T5-Lib</a> by Laurent Guérin et Julien Maupoux</p><blockquote><p>A library of components: accordion, ajax loader, slider, tab view, secured password, color picker, tooltip, hideable panel and more! Live demo is provided.</p></blockquote><p><a shape="rect" class="external-link" href="http://code.google.com/p/flowlogix/" >FlowLogix</a> by Lenny Primak</p><blockquote><p>a c
ollection of components, services and utilities that integrates Tapestry into JEE environments and provides other commonly needed functionality.</p></blockquote><p><a shape="rect" href="modules.html">More Modules</a>...</p><h1 id="Community-Extensions">Extensions</h1><p><a shape="rect" class="external-link" href="http://www.arsmachina.com.br/" >Ars Machina</a> by Thiago H. de Paula Figueiredo</p><blockquote><p>Tapestry/Hibernate extensions for Generic DAOs, standard CRUD interfaces, and user access logging and tracking.</p></blockquote><p><a shape="rect" class="external-link" href="http://tynamo.org/" >Tynamo project</a> by Tynamo Team / Kalle Korhonen & Alejandro Scandroli</p><blockquote><p>Tynamo is model-driven, full-stack web framework based on Tapestry 5, allowing you to jump directly from your Hibernate entities to a full-blown CRUD application. Tynamo provides several modules, including tapestry-model, tapestry-conversations, tapestry-hibernate-seedentity, tapestry-restea
sy and tapestry-security.</p></blockquote></div><div class="columnMacro"><h1 id="Community-Tutorials">Tutorials</h1><p><a shape="rect" class="external-link" href="http://jumpstart.doublenegative.com.au/jumpstart" >Tapestry JumpStart</a> by Geoff Callender</p><blockquote><p>JumpStart is an easy way to learn Tapestry by example. It's an online demo application, and also a downloadable open source app ready for you to explore and modify.</p></blockquote><p><a shape="rect" class="external-link" href="http://tapestry-stitch.uklance.cloudbees.net/" >Tapestry Stitch</a> by Lance</p><blockquote><p>Sample components and concepts in Apache Tapestry 5</p></blockquote><p><a shape="rect" class="external-link" href="http://code.google.com/p/shams/" >Shams Examples</a> by Mohammad H. Shamsi</p><blockquote><p>A variety of examples of Tapestry 5 pages and components.</p></blockquote><p><a shape="rect" class="external-link" href="http://wiki.apache.org/tapestry/FrontPage">Community's Wiki</a> (Moin M
oin)</p><blockquote><p>The wiki contains a wealth of user-generated tips and techniques for using Tapestry</p></blockquote><h1 id="Community-IDEIntegrations">IDE Integrations</h1><p><a shape="rect" class="external-link" href="https://github.com/anjlab/eclipse-tapestry5-plugin" >Eclipse-tapestry5-plugin</a></p><blockquote><p>An Eclipse plugin for Tapestry 5 by Dmitry Gusev, with a "Quick Switch" between templates and component classes, a Tapestry Context view, and many other convenience features. <span style="color: rgb(112,112,112);">This is currently the best choice for Eclipse users.</span></p></blockquote><p><a shape="rect" class="external-link" href="http://code.google.com/p/tapestrytools/wiki/Install_Guide_Lightweight_TapestryTools" >Tapestry Tools</a> by Gavin Lei</p><blockquote><p>Tapestry Tools is an Eclipse plugin for Tapestry 5 which has been built by Gavin Lei within the timeframe of GSoC 2012.</p></blockquote><p><a shape="rect" class="external-link" href="http://www.jetb
rains.com/idea" >IntelliJ 10</a> by JetBrains</p><blockquote><p>IntelliJ has Tapestry 5 support included <a shape="rect" class="external-link" href="http://www.jetbrains.com/idea/features/tapestry_5.html" >right out of the box</a>.</p></blockquote><p><a shape="rect" class="external-link" href="http://code.google.com/p/loom-t5/" >loom-t5</a> by Chris Scheid</p><blockquote><p>Eclipse plugin for building Tapestry 5 projects</p></blockquote><p><a shape="rect" class="external-link" href="http://wiki.apache.org/tapestry/Tapestry5JSPEditorEclipse">Code Completion in Eclipse</a></p><blockquote><p>How to use the built in JSP Eclipse Editor and a custom tld file to get Tapestry 5 code completion in Eclipse</p></blockquote></div></div></div></div></div></div>
</div>
<div class="clearer"></div>
Modified: websites/production/tapestry/content/developer-bible.html
==============================================================================
--- websites/production/tapestry/content/developer-bible.html (original)
+++ websites/production/tapestry/content/developer-bible.html Sat Feb 8 15:20:40 2014
@@ -85,7 +85,7 @@
<span class="icon icon-page" title="Page">Page:</span> </div>
<div class="details">
- <a shape="rect" href="developer-bible.html">Developer Bible</a>
+ <a shape="rect" href="confluence-site-setup.html">Confluence Site Setup</a>
</div>
@@ -94,7 +94,7 @@
<span class="icon icon-page" title="Page">Page:</span> </div>
<div class="details">
- <a shape="rect" href="confluence-site-setup.html">Confluence Site Setup</a>
+ <a shape="rect" href="release-process.html">Release Process</a>
</div>
@@ -103,7 +103,7 @@
<span class="icon icon-page" title="Page">Page:</span> </div>
<div class="details">
- <a shape="rect" href="developer-information.html">Developer Information</a>
+ <a shape="rect" href="building-tapestry-from-source.html">Building Tapestry from Source</a>
</div>
@@ -112,7 +112,7 @@
<span class="icon icon-page" title="Page">Page:</span> </div>
<div class="details">
- <a shape="rect" href="release-process.html">Release Process</a>
+ <a shape="rect" href="developer-information.html">Developer Information</a>
</div>
@@ -121,125 +121,13 @@
<span class="icon icon-page" title="Page">Page:</span> </div>
<div class="details">
- <a shape="rect" href="building-tapestry-from-source.html">Building Tapestry from Source</a>
+ <a shape="rect" href="developer-bible.html">Developer Bible</a>
</div>
</li></ul>
-</div>
-
-<p>This is a semi-random outpouring of thoughts related to being a Tapestry committer.</p>
-
-<h2 id="DeveloperBible-IDEChoices">IDE Choices</h2>
-
-<h3 id="DeveloperBible-IntelliJ">IntelliJ</h3>
-
-<p>It's a free license for all committers and it's just better. Yes, the first few days can be an unpleasant fumble because everything is almost, but not quite, familiar. Pretty soon you'll love IDEA and recognize that Eclipse has been bending you over and doing unspeakable things.</p>
-
-<p>There are shared code formatting settings in the <a shape="rect" class="external-link" href="https://git-wip-us.apache.org/repos/asf?p=tapestry-5.git;a=tree;f=support">support directory</a> (idea-settings.jar). This will prevent unexpected conflicts due to formatting.</p>
-
-<h3 id="DeveloperBible-Eclipse">Eclipse</h3>
-
-<p>Howard uses this ... because he can't manage to switch IDEs constantly (he uses Eclipse for training). Lately its gotten better.</p>
-
-<p>As with IntelliJ, there are shared code formatting settings for Eclipse in the <a shape="rect" class="external-link" href="https://git-wip-us.apache.org/repos/asf?p=tapestry-5.git;a=tree;f=support">support directory</a> (tapestry-indent-eclipse.xml).</p>
-
-<h2 id="DeveloperBible-Copyrights">Copyrights</h2>
-
-<p>All source files should have the ASF copyright comment on top, except where such a comment would interfere with its behavior. For example, component template files omit the comment.</p>
-
-<p>As you make changes to files, update the copyright to add the current year to the list. The goal is that the copyright notice includes the year in which files change. When creating a new file, don't back date the copyright year ... start with the current year. Try not to change the copyright year on files that haven't actually changed.</p>
-
-<p>IntelliJ has a great comparison view: Cmd-9 to see the local changes, the Cmd-D to see the differences. You can whip through the changes (using Cmd-forward arrow) and make sure copyrights are up to date as you review the changes prior to a commit.</p>
-
-<h2 id="DeveloperBible-CommitMessages">Commit Messages</h2>
-
-<p>Always provide a commit message. Howard generally tries to work off the JIRA, so his commit message is often:</p>
-
-<blockquote><p>TAP5-1234: Make the Foo Widget more Ajax-tastic!</p></blockquote>
-
-<p>It is <em>very important</em> to include the JIRA issue id in the commit. This is used in many places: JIRA links issues to the SVN commits for that issue (very handy for seeing what changed as part of a bug fix). The Hudson CI server does as well, and will actually link SVN commits to issues after succesfully building.</p>
-
-<h2 id="DeveloperBible-JIRAProcedures">JIRA Procedures</h2>
-
-<p>All Tapestry committers should be registerred with JIRA and part of the tapestry-developers JIRA group.</p>
-
-<p>Every committer is invited to look at the list of <a shape="rect" class="external-link" href="https://issues.apache.org/jira/secure/IssueNavigator.jspa?mode=hide&requestId=12317068">'Review for closing'</a> issues and review them as it contains probably outdated or no more valid issues.</p>
-
-<p>There's also a list of all <a shape="rect" class="external-link" href="https://issues.apache.org/jira/secure/IssueNavigator.jspa?mode=hide&requestId=12316792">Open</a> issue about the project.</p>
-
-<p>Ideally, we would always work top priortity to low priority. Howard sometimes jump out of order, if there's something cool to work on that fits in an available time slot. Alternately, you are always allowed to change the priority of a bug before or as you work it.</p>
-
-<p>As a general rule issues which are "<em>Invalid</em>" or "<em>Won't</em> <em>Fix</em>" shouldn't have a "<em>Fix</em> <em>version</em>".</p>
-
-<h3 id="DeveloperBible-Startingwork">Starting work </h3>
-
-<p>When you start to work on an issue, make sure it is <em>assigned to you</em> and use the <em>start progress</em> option.</p>
-
-<p>Add comments about the state of the fix, or the challenges in creating a fix. This often spurs the Issue's adder to<br clear="none">
-provide more details.</p>
-
-<p>Update the issue description to make it more legible and more precise if needed, i.e., "NPE in CheckUpdates" might become "NullPointerException when checking for updates to files that have been deleted". Verbose is good.</p>
-
-<h3 id="DeveloperBible-Closingbugs">Closing bugs </h3>
-
-<p>Is it a bug fix without tests? <strong>No.</strong> A good plan is to write a test that fails then work the code until the test passes. Often code works in a unit test but fails unexpectedly in an integration test. As the G-Man says <em>"Expect unforeseen consequences"</em>.</p>
-
-<p>When you check in a fix, you should <strong>close</strong> the issue and make sure the <strong>fix release</strong> is correct.</p>
-
-<p>We're playing fast and loose – a better procedure would be to mark the bug resolved and verify the fix before closing it. That's ok, we have a community to double check our work <img class="emoticon emoticon-smile" src="https://cwiki.apache.org/confluence/s/en_GB-1988229788/4109/76e0dbb30bc8580e459c201f3535d84f9283a9ac.1/_/images/icons/emoticons/smile.png" data-emoticon-name="smile" alt="(smile)">.</p>
-
-<p>For anything non-trivial, wait for the Hudson CI server to build. It catches a lot of things ... such as files that were not added to SVN. And even IntelliJ has a bit of trouble with wildly refactored code. Hudson will catch all that.</p>
-
-<h3 id="DeveloperBible-Invalidissuesandduplicates">Invalid issues and duplicates</h3>
-
-<p>Always provide comments about why_ an issue is invalid (<em>"A Ruby implementation of Tapestry is out of scope for the project."</em>), or at least, a link to the duplicate issues.</p>
-
-<p>Consider writing new tests to prove that an issue is not valid and then leave the tests in place – then close the bug as invalid.</p>
-
-<p>Close the issue but <em>make sure the fix release is blank</em>. Otherwise, the issue <em>will be listed in the release notes</em>, which we don't want.</p>
-
-<h2 id="DeveloperBible-Publicvs.Private/Internal">Public vs. Private/Internal</h2>
-
-<p>This is a real big deal. As long as code is in the internal package, we have a high degree of carte-blanche to change it. As soon as code is public, we become handcuffed to backwards compatibility.</p>
-
-<p><em>Interfaces are public, implementations are private</em>. You can see this is the bulk of the code, where org.apache.tapestry5.services is almost all interfaces and the implementations are in org.apache.tapestry5.internal.services.</p>
-
-<p>Many more services have both the interface and the implementation in org.apache.tapestry5.internal.services.</p>
-
-<p>We absolutely <em>do not</em> want to make Page or ComponentPageElement public. You will often see public service facades that take a page name as a method parameter, and convert it to a page instance before invoking methods on internal services.</p>
-
-<h2 id="DeveloperBible-EvolvingComponents">Evolving Components</h2>
-
-<p>We do not have a specific plan for this yet. Future Tapestry 5 will add features to allow clean renames of parameters, and a way to deprecated and eventually remove components.</p>
-
-<h2 id="DeveloperBible-EvolvingInterfaces">Evolving Interfaces</h2>
-
-<p>Tapestry uses interfaces quite extensively.</p>
-
-<p>Interfaces fall into two categories: service interfaces called by user code, and interfaces implemented by user code.</p>
-
-<p>Internal interfaces may be changed at any time. That's why so much is kept internal.</p>
-
-<h3 id="DeveloperBible-ServiceInterfaces">Service Interfaces</h3>
-
-<p>New methods may be added if absolutely necessary, but this should be avoided if at all possible. Don't forget the <code>@since</code> Javadoc annotation.</p>
-
-<p>Consider having a stable public facade service whose implementation calls into one or more internal service.</p>
-
-<h3 id="DeveloperBible-UserInterfaces">User Interfaces</h3>
-
-<p>These should be frozen, no changes once released. Failure to do so causes <em>non-backwards compatible upgrade problems</em>; that is, classes that implement the (old) interface are suddenly invalid, missing methods from the (new) interface.</p>
-
-<p>Consider introducing a new interface that extends the old one and adds new methods. Make sure you support both.</p>
-
-<p>You can see this with ServiceDef and ServiceDef2 (which extends ServiceDef). Yes this can be a bit ugly.</p>
-
-<p>Howard uses utility methods that convert from ServiceDef to ServiceDef2, adding a wrapper implementation around a ServiceDef instance if necessary:</p>
-
-<div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[
- public static ServiceDef2 toServiceDef2(final ServiceDef sd)
+</div><p>IDE choices, coding style and formatting, commit practices, naming conventions and other issues relevant to Tapestry committers & contributers.</p><h2 id="DeveloperBible-IDEChoices">IDE Choices</h2><h3 id="DeveloperBible-IntelliJ">IntelliJ</h3><p>It's a free license for all committers and it's just better. Yes, the first few days can be an unpleasant fumble because everything is almost, but not quite, familiar. Pretty soon you'll love IDEA and recognize that Eclipse has been bending you over and doing unspeakable things.</p><p>There are shared code formatting settings in the <a shape="rect" class="external-link" href="https://git-wip-us.apache.org/repos/asf?p=tapestry-5.git;a=tree;f=support">support directory</a> (idea-settings.jar). This will prevent unexpected conflicts due to formatting.</p><h3 id="DeveloperBible-Eclipse">Eclipse</h3><p>Howard uses this ... because he can't manage to switch IDEs constantly (he uses Eclipse for training). Lately its gotten better.</p>
<p>As with IntelliJ, there are shared code formatting settings for Eclipse in the <a shape="rect" class="external-link" href="https://git-wip-us.apache.org/repos/asf?p=tapestry-5.git;a=tree;f=support">support directory</a> (tapestry-indent-eclipse.xml).</p><h2 id="DeveloperBible-Copyrights">Copyrights</h2><p>All source files should have the ASF copyright comment on top, except where such a comment would interfere with its behavior. For example, component template files omit the comment.</p><p>As you make changes to files, update the copyright to add the current year to the list. The goal is that the copyright notice includes the year in which files change. When creating a new file, don't back date the copyright year ... start with the current year. Try not to change the copyright year on files that haven't actually changed.</p><p>IntelliJ has a great comparison view: Cmd-9 to see the local changes, the Cmd-D to see the differences. You can whip through the changes (using Cmd-forward
arrow) and make sure copyrights are up to date as you review the changes prior to a commit.</p><h2 id="DeveloperBible-CommitMessages">Commit Messages</h2><p>Always provide a commit message. Howard generally tries to work off the JIRA, so his commit message is often:</p><blockquote><p>TAP5-1234: Make the Foo Widget more Ajax-tastic!</p></blockquote><p>It is <em>very important</em> to include the JIRA issue id in the commit. This is used in many places: JIRA links issues to the Git commits for that issue (very handy for seeing what changed as part of a bug fix). The Hudson CI server does as well, and will actually link Git commits to issues after succesfully building.</p><h2 id="DeveloperBible-JIRAProcedures">JIRA Procedures</h2><p>All Tapestry committers should be registerred with JIRA and part of the tapestry-developers JIRA group.</p><p>Every committer is invited to look at the list of <a shape="rect" class="external-link" href="https://issues.apache.org/jira/secure/Issu
eNavigator.jspa?mode=hide&requestId=12317068">'Review for closing'</a> issues and review them as it contains probably outdated or no more valid issues.</p><p>There's also a list of all <a shape="rect" class="external-link" href="https://issues.apache.org/jira/secure/IssueNavigator.jspa?mode=hide&requestId=12316792">Open</a> issue about the project.</p><p>Ideally, we would always work top priortity to low priority. Howard sometimes jump out of order, if there's something cool to work on that fits in an available time slot. Alternately, you are always allowed to change the priority of a bug before or as you work it.</p><p>As a general rule issues which are "<em>Invalid</em>" or "<em>Won't</em> <em>Fix</em>" shouldn't have a "<em>Fix</em> <em>version</em>".</p><h3 id="DeveloperBible-Startingwork">Starting work</h3><p>When you start to work on an issue, make sure it is <em>assigned to you</em> and use the <em>start progress</em> option.</p><p>Add comments about the state of the
fix, or the challenges in creating a fix. This often spurs the Issue's adder to<br clear="none"> provide more details.</p><p>Update the issue description to make it more legible and more precise if needed, i.e., "NPE in CheckUpdates" might become "NullPointerException when checking for updates to files that have been deleted". Verbose is good.</p><h3 id="DeveloperBible-Closingbugs">Closing bugs</h3><p>Is it a bug fix without tests? <strong>No.</strong> A good plan is to write a test that fails then work the code until the test passes. Often code works in a unit test but fails unexpectedly in an integration test. As the G-Man says <em>"Expect unforeseen consequences"</em>.</p><p>When you check in a fix, you should <strong>close</strong> the issue and make sure the <strong>fix release</strong> is correct.</p><p>We're playing fast and loose – a better procedure would be to mark the bug resolved and verify the fix before closing it. That's ok, we have a community to double check o
ur work <img class="emoticon emoticon-smile" src="https://cwiki.apache.org/confluence/s/en_GB-1988229788/4109/76e0dbb30bc8580e459c201f3535d84f9283a9ac.1/_/images/icons/emoticons/smile.png" data-emoticon-name="smile" alt="(smile)">.</p><p>For anything non-trivial, wait for the Hudson CI server to build. It catches a lot of things ... such as files that were not added to Git. And even IntelliJ has a bit of trouble with wildly refactored code. Hudson will catch all that.</p><h3 id="DeveloperBible-Invalidissuesandduplicates">Invalid issues and duplicates</h3><p>Always provide comments about why_ an issue is invalid (<em>"A Ruby implementation of Tapestry is out of scope for the project."</em>), or at least, a link to the duplicate issues.</p><p>Consider writing new tests to prove that an issue is not valid and then leave the tests in place – then close the bug as invalid.</p><p>Close the issue but <em>make sure the fix release is blank</em>. Otherwise, the issue <em>will be listed
in the release notes</em>, which we don't want.</p><h2 id="DeveloperBible-Publicvs.Private/Internal">Public vs. Private/Internal</h2><p>This is a real big deal. As long as code is in the internal package, we have a high degree of carte-blanche to change it. As soon as code is public, we become handcuffed to backwards compatibility.</p><p><em>Interfaces are public, implementations are private</em>. You can see this is the bulk of the code, where org.apache.tapestry5.services is almost all interfaces and the implementations are in org.apache.tapestry5.internal.services.</p><p>Many more services have both the interface and the implementation in org.apache.tapestry5.internal.services.</p><p>We absolutely <em>do not</em> want to make Page or ComponentPageElement public. You will often see public service facades that take a page name as a method parameter, and convert it to a page instance before invoking methods on internal services.</p><h2 id="DeveloperBible-EvolvingComponents">Evolvin
g Components</h2><p>We do not have a specific plan for this yet. Future Tapestry 5 will add features to allow clean renames of parameters, and a way to deprecated and eventually remove components.</p><h2 id="DeveloperBible-EvolvingInterfaces">Evolving Interfaces</h2><p>Tapestry uses interfaces quite extensively.</p><p>Interfaces fall into two categories: service interfaces called by user code, and interfaces implemented by user code.</p><p>Internal interfaces may be changed at any time. That's why so much is kept internal.</p><h3 id="DeveloperBible-ServiceInterfaces">Service Interfaces</h3><p>New methods may be added if absolutely necessary, but this should be avoided if at all possible. Don't forget the <code>@since</code> Javadoc annotation.</p><p>Consider having a stable public facade service whose implementation calls into one or more internal service.</p><h3 id="DeveloperBible-UserInterfaces">User Interfaces</h3><p>These should be frozen, no changes once released. Failure to do
so causes <em>non-backwards compatible upgrade problems</em>; that is, classes that implement the (old) interface are suddenly invalid, missing methods from the (new) interface.</p><p>Consider introducing a new interface that extends the old one and adds new methods. Make sure you support both.</p><p>You can see this with ServiceDef and ServiceDef2 (which extends ServiceDef). Yes this can be a bit ugly.</p><p>Howard uses utility methods that convert from ServiceDef to ServiceDef2, adding a wrapper implementation around a ServiceDef instance if necessary:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[ public static ServiceDef2 toServiceDef2(final ServiceDef sd)
{
if (sd instanceof ServiceDef2)
return (ServiceDef2) sd;
@@ -260,119 +148,7 @@ provide more details.</p>
};
}
]]></script>
-</div></div>
-
-<h2 id="DeveloperBible-Useof@since">Use of @since</h2>
-
-<p>When adding new classes or interface, or adding new methods to existing types, add an @since Javadoc comment.</p>
-
-<p>Use the complete version number of the release in which the type or method was added: i.e., <em>@since 5.1.0.3</em>.</p>
-
-<h2 id="DeveloperBible-CodeStyle">Code Style</h2>
-
-<p>Yes, at one time Howard used leading underscores for field names. He has since changed my mind, but this unfortunately infected other people; please try to make your code blend in when modifying existing source.</p>
-
-<p>Long ago, Tapestry (3) code used the regrettable "leading-I-on-interfaces" style. Don't do that. Everything's an interface.</p>
-
-<p>Howard prefers braces on a new line (and thus, open braces lined up with close braces), so that's what the default code formatting is set up for. It's okay to omit braces for trivial if statements, such as <code>if (!test) return;</code>. </p>
-
-<p>Use a lot of vertical whitespace to break methods into logical sections.</p>
-
-<p>We're coding Java, not Pascal; it's better to have a few checks early on with quick returns or exceptions than have ten-levels deep block nesting just so a method can have a single return statement. In other words, <em>else considered harmful</em>. Low code complexity is better, more readable, more maintainable code.</p>
-
-<p>Don't bother alphabetizing things, because the IDE lets you jump around easily.</p>
-
-<p><em>Final is the new private.</em> Final fields are great for multi-threaded code. Especially when creating service implementations with dependencies, store those dependencies into final fields. Once we're all running on 100 core workstations, you'll thank me. Seriously, Java's memory model is seriously twisted stuff, and assigning to a non-final field from a constructor opens up a tiny window of non-thread safety.</p>
-
-<h2 id="DeveloperBible-Comments">Comments</h2>
-
-<p>Comments are overwhelmingly important. Try to capture the <em>why</em> of a class or method. Add lots of links, to code that will be invoked by the method, to related methods or classes, and so forth. For instance, you may often have an annotation, a worker class for the annotation, and a related service all cross-linked.</p>
-
-<p>Comment the <em>interfaces</em> and don't get worked up on the <em>implementations</em>. Javadoc does a perfectly good job of copying interface comments to implementations, so this falls under the <em>Don't Repeat Yourself</em> guideline.</p>
-
-<p>Be very careful about documenting what methods can accept null, and what methods may return null. Generally speaking, people will assume that null is not allowed for parameters, and method will never return null, unless it is explicitly documented that null is allowed (or potentially returned).</p>
-
-<h2 id="DeveloperBible-Documentation">Documentation</h2>
-
-<p>Try and keep the documentation up-to date as you make changes; it is <em>much</em> harder to do so later. This is now much easier using the Confluence wiki (you're reading the result <img class="emoticon emoticon-smile" src="https://cwiki.apache.org/confluence/s/en_GB-1988229788/4109/76e0dbb30bc8580e459c201f3535d84f9283a9ac.1/_/images/icons/emoticons/smile.png" data-emoticon-name="smile" alt="(smile)">).</p>
-
-<p>Documentation is the <em>#1 criticism</em> of Tapestry!</p>
-
-<h2 id="DeveloperBible-ClassandMethodNamingConventions">Class and Method Naming Conventions</h2>
-
-<p>Naming things is hard. Names that make sense to one person won't to another.</p>
-
-<p>That being said, Howard has tried to be somewhat consistent with naming. Not perfectly.</p>
-
-<h3 id="DeveloperBible-Factory,Creator">Factory, Creator</h3>
-
-<p>A factory class creates new objects. Methods will often be prefixed with "create" or "new". Don't expect a Factory to cache anything, it just creates new things.</p>
-
-<h3 id="DeveloperBible-Source">Source</h3>
-
-<p>A source is a level up from a Factory. It <em>may</em> combine multiple factories together. It <em>usually</em> will cache the result. Method are often prefixed with "get".</p>
-
-<h3 id="DeveloperBible-Findvs.Get">Find vs. Get</h3>
-
-<p>For methods: A "find" prefix indicates that a non-match is valid and null may be returned. A "get" prefix indicates that a non-match is invalid and an exception will be thrown in that case (and null will never be returned).</p>
-
-<h3 id="DeveloperBible-Contribution">Contribution</h3>
-
-<p>A data object usually associated with a Tapestry IoC service's configuration.</p>
-
-<h3 id="DeveloperBible-Filter">Filter</h3>
-
-<p>Part of a pipeline, where there's an associated main interface, and the Filter wraps around that main interface. Each main interface method is duplicated in the Filter, with an extra parameter used to chain the interface.</p>
-
-<h3 id="DeveloperBible-Manager">Manager</h3>
-
-<p>Often a wrapper around a service configuration, it provides access to the contributed values (possibly after some transformation).</p>
-
-<h3 id="DeveloperBible-To">To</h3>
-
-<p>A method prefix that indicates a conversion or coersion from one type to another. I.e., <code>toUserPresentable()</code>.</p>
-
-<h3 id="DeveloperBible-Worker">Worker</h3>
-
-<p>An object that peforms a specific job. Workers will be stateless, but will be passed a stateful object to perform some operation upon.</p>
-
-<h3 id="DeveloperBible-Builder">Builder</h3>
-
-<p>An object whose job is to create other objects, typically in the context of creating a core service implementation for a Tapestry IoC service (such as PipelineBuilder or ChainBuilder).</p>
-
-<h3 id="DeveloperBible-Support">Support</h3>
-
-<p>An object that provides supporting operations to other objects; this is a kind of "loose aggregation".</p>
-
-<h3 id="DeveloperBible-Parameters">Parameters</h3>
-
-<p>A data object that holds a number of related values that would otherwise be separate parameter values to a method. This tends to streamline code (especially when using a Filter interface) and allows the parameters to be evolved without changing the method signature.</p>
-
-<h3 id="DeveloperBible-Strategy">Strategy</h3>
-
-<p>An object that "plugs into" some other code, allowing certain decisions to be deferred to the Strategy. Often a Strategy is selected based on the type of some object being operated upon.</p>
-
-<h3 id="DeveloperBible-Context">Context</h3>
-
-<p>Captures some stateful information that may be passed around between stateless services.</p>
-
-<h3 id="DeveloperBible-Constants">Constants</h3>
-
-<p>A non-instantiable class that contains public static fields that are referenced in multiple places.</p>
-
-<h3 id="DeveloperBible-Hub">Hub</h3>
-
-<p>An object that allows listeners to be registered. Often includes a method prefixed with "trigger" that will send notifications to listeners.</p>
-
-<h2 id="DeveloperBible-ImplementtoString()">Implement <code>toString()</code></h2>
-
-<p>Objects that are exposed to user code should generally implement a meaningful toString() method. And that method should be tested.</p>
-
-<h2 id="DeveloperBible-Subclassing">Subclassing</h2>
-
-<p>You'll notice there isn't a lot of inheritance in Tapestry. Given the function of the IoC container, it is much more common to use some variation of <em>aggregation</em> rather than <em>inheritance</em>.</p>
-
-<p>Where subclassing exists, the guideline for constructor parameters is: the subclass should include all the constructor parameters of the superclass, in the same positions. Thus subclass constructor parameters are appended to the list of super-class constructor parameters.</p></div>
+</div></div><h2 id="DeveloperBible-Useof@since">Use of @since</h2><p>When adding new classes or interface, or adding new methods to existing types, add an @since Javadoc comment.</p><p>Use the complete version number of the release in which the type or method was added: i.e., <em>@since 5.1.0.3</em>.</p><h2 id="DeveloperBible-CodeStyle&Formatting">Code Style & Formatting</h2><p>Yes, at one time Howard used leading underscores for field names. He has since changed my mind, but this unfortunately infected other people; please try to make your code blend in when modifying existing source.</p><p>Long ago, Tapestry (3) code used the regrettable "leading-I-on-interfaces" style. Don't do that. Instead, name the implementation class with an "Impl" at the end.</p><p>Howard prefers braces on a new line (and thus, open braces lined up with close braces), so that's what the default code formatting is set up for. It's okay to omit braces for trivial one-liner if statements, such as <code
>if (!test) return;</code>.</p><p>Indent with 4 spaces instead of tabs.</p><p>Use a lot of vertical whitespace to break methods into logical sections.</p><p>We're coding Java, not Pascal; it's better to have a few checks early on with quick returns or exceptions than have ten-levels deep block nesting just so a method can have a single return statement. In other words, <em>else considered harmful</em>. Low code complexity is better, more readable, more maintainable code.</p><p>Don't bother alphabetizing things, because the IDE lets you jump around easily.</p><p><em>Final is the new private.</em> Final fields are great for multi-threaded code. Especially when creating service implementations with dependencies, store those dependencies into final fields. Once we're all running on 100 core workstations, you'll thank me. Seriously, Java's memory model is seriously twisted stuff, and assigning to a non-final field from a constructor opens up a tiny window of non-thread safety.</p><h2 id=
"DeveloperBible-Comments">Comments</h2><p>Comments are overwhelmingly important. Try to capture the <em>why</em> of a class or method. Add lots of links, to code that will be invoked by the method, to related methods or classes, and so forth. For instance, you may often have an annotation, a worker class for the annotation, and a related service all cross-linked.</p><p>Comment the <em>interfaces</em> and don't get worked up on the <em>implementations</em>. Javadoc does a perfectly good job of copying interface comments to implementations, so this falls under the <em>Don't Repeat Yourself</em> guideline.</p><p>Be very careful about documenting what methods can accept null, and what methods may return null. Generally speaking, people will assume that null is not allowed for parameters, and method will never return null, unless it is explicitly documented that null is allowed (or potentially returned).</p><h2 id="DeveloperBible-Documentation">Documentation</h2><p>Try and keep the docum
entation up-to date as you make changes; it is <em>much</em> harder to do so later. This is now much easier using the Confluence wiki (you're reading the result <img class="emoticon emoticon-smile" src="https://cwiki.apache.org/confluence/s/en_GB-1988229788/4109/76e0dbb30bc8580e459c201f3535d84f9283a9ac.1/_/images/icons/emoticons/smile.png" data-emoticon-name="smile" alt="(smile)">).</p><p>Documentation was at one point the <em>#1 criticism</em> of Tapestry!</p><h2 id="DeveloperBible-ClassandMethodNamingConventions">Class and Method Naming Conventions</h2><p>Naming things is hard. Names that make sense to one person won't to another.</p><p>That being said, Howard has tried to be somewhat consistent with naming. Not perfectly.</p><h3 id="DeveloperBible-Factory,Creator">Factory, Creator</h3><p>A factory class creates new objects. Methods will often be prefixed with "create" or "new". Don't expect a Factory to cache anything, it just creates new things.</p><h3 id="DeveloperBible-Source"
>Source</h3><p>A source is a level up from a Factory. It <em>may</em> combine multiple factories together. It <em>usually</em> will cache the result. Method are often prefixed with "get".</p><h3 id="DeveloperBible-Findvs.Get">Find vs. Get</h3><p>For methods: A "find" prefix indicates that a non-match is valid and null may be returned. A "get" prefix indicates that a non-match is invalid and an exception will be thrown in that case (and null will never be returned).</p><h3 id="DeveloperBible-Contribution">Contribution</h3><p>A data object usually associated with a Tapestry IoC service's configuration.</p><h3 id="DeveloperBible-Filter">Filter</h3><p>Part of a pipeline, where there's an associated main interface, and the Filter wraps around that main interface. Each main interface method is duplicated in the Filter, with an extra parameter used to chain the interface.</p><h3 id="DeveloperBible-Manager">Manager</h3><p>Often a wrapper around a service configuration, it provides access to
the contributed values (possibly after some transformation).</p><h3 id="DeveloperBible-To">To</h3><p>A method prefix that indicates a conversion or coersion from one type to another. I.e., <code>toUserPresentable()</code>.</p><h3 id="DeveloperBible-Worker">Worker</h3><p>An object that peforms a specific job. Workers will be stateless, but will be passed a stateful object to perform some operation upon.</p><h3 id="DeveloperBible-Builder">Builder</h3><p>An object whose job is to create other objects, typically in the context of creating a core service implementation for a Tapestry IoC service (such as PipelineBuilder or ChainBuilder).</p><h3 id="DeveloperBible-Support">Support</h3><p>An object that provides supporting operations to other objects; this is a kind of "loose aggregation".</p><h3 id="DeveloperBible-Parameters">Parameters</h3><p>A data object that holds a number of related values that would otherwise be separate parameter values to a method. This tends to streamline code (
especially when using a Filter interface) and allows the parameters to be evolved without changing the method signature.</p><h3 id="DeveloperBible-Strategy">Strategy</h3><p>An object that "plugs into" some other code, allowing certain decisions to be deferred to the Strategy. Often a Strategy is selected based on the type of some object being operated upon.</p><h3 id="DeveloperBible-Context">Context</h3><p>Captures some stateful information that may be passed around between stateless services.</p><h3 id="DeveloperBible-Constants">Constants</h3><p>A non-instantiable class that contains public static fields that are referenced in multiple places.</p><h3 id="DeveloperBible-Hub">Hub</h3><p>An object that allows listeners to be registered. Often includes a method prefixed with "trigger" that will send notifications to listeners.</p><h2 id="DeveloperBible-ImplementtoString()">Implement <code>toString()</code></h2><p>Objects that are exposed to user code should generally implement a meanin
gful toString() method. And that method should be tested.</p><h2 id="DeveloperBible-Subclassing">Subclassing</h2><p>You'll notice there isn't a lot of inheritance in Tapestry. Given the function of the IoC container, it is much more common to use some variation of <em>aggregation</em> rather than <em>inheritance</em>.</p><p>Where subclassing exists, the guideline for constructor parameters is: the subclass should include all the constructor parameters of the superclass, in the same positions. Thus subclass constructor parameters are appended to the list of super-class constructor parameters.</p></div>
</div>
<div class="clearer"></div>
Modified: websites/production/tapestry/content/developer-information.html
==============================================================================
--- websites/production/tapestry/content/developer-information.html (original)
+++ websites/production/tapestry/content/developer-information.html Sat Feb 8 15:20:40 2014
@@ -61,16 +61,7 @@
</div>
<div id="content">
-<div id="ConfluenceContent"><p>This is a list of information useful to people <em>developing</em> Tapestry itself (rather than developers <em>using</em> Tapestry).</p>
-
-<h2 id="DeveloperInformation-HowTos">How Tos</h2>
-
-<ul><li><a shape="rect" href="confluence-site-setup.html">Confluence Site Setup</a> – all about how Confluence is used to edit the content of the static documentation site</li><li><a shape="rect" href="release-process.html">Release Process</a> – how to produce a release</li><li><a shape="rect" href="developer-bible.html">Developer Bible</a> – random thoughts from Howard related to being a Tapestry committer</li><li><a shape="rect" href="building-tapestry-from-source.html">Building Tapestry from Source</a> – how to build Tapestry itself</li><li><a shape="rect" href="version-numbers.html">Version Numbers</a></li></ul>
-
-
-<h2 id="DeveloperInformation-DeveloperTools&Reports">Developer Tools & Reports</h2>
-
-<ul><li><a shape="rect" class="external-link" href="https://builds.apache.org/job/tapestry-trunk-freestyle/">Jenkins automated build results</a> – trunk</li><li><a shape="rect" class="external-link" href="http://tapestry.apache.org/5.2/tapestry-core/cobertura/index.html">Cobertura code coverage report</a> – measures test coverage</li><li><a shape="rect" class="external-link" href="https://analysis.apache.org/dashboard/index/org.apache.tapestry:tapestry-project">Sonar code quality report</a> – measures test coverage, complexity & rule violations</li><li><a shape="rect" class="external-link" href="https://git-wip-us.apache.org/repos/asf?p=tapestry-5.git">Browse Git source</a></li><li><a shape="rect" href="the-tapestry-jail.html">The Tapestry Jail</a> – information about our FreeBSD jail at typestry.zones.apache.org</li></ul></div>
+<div id="ConfluenceContent"><p>This is a list of information useful to people <em>developing</em> Tapestry itself (rather than developers <em>using</em> Tapestry).</p><h2 id="DeveloperInformation-HowTos">How Tos</h2><ul><li><a shape="rect" href="confluence-site-setup.html">Confluence Site Setup</a> – all about how Confluence is used to edit the content of the static documentation site</li><li><a shape="rect" href="release-process.html">Release Process</a> – how to produce a release</li><li><a shape="rect" href="developer-bible.html">Developer Bible</a> – coding & committing advice, including IDE choices, coding style, class naming conventions and bug tracking policies</li><li><a shape="rect" href="building-tapestry-from-source.html">Building Tapestry from Source</a> – how to build Tapestry itself</li><li><a shape="rect" href="version-numbers.html">Version Numbers</a></li></ul><h2 id="DeveloperInformation-DeveloperTools&Reports">Develope
r Tools & Reports</h2><ul><li><a shape="rect" class="external-link" href="https://builds.apache.org/job/tapestry-trunk-freestyle/">Jenkins automated build results</a> – trunk</li><li><a shape="rect" class="external-link" href="http://tapestry.apache.org/5.2/tapestry-core/cobertura/index.html">Cobertura code coverage report</a> – measures test coverage</li><li><a shape="rect" class="external-link" href="https://analysis.apache.org/dashboard/index/org.apache.tapestry:tapestry-project">Sonar code quality report</a> – measures test coverage, complexity & rule violations</li><li><a shape="rect" class="external-link" href="https://git-wip-us.apache.org/repos/asf?p=tapestry-5.git">Browse Git source</a></li><li><a shape="rect" href="the-tapestry-jail.html">The tapestry jail</a> – information about our FreeBSD jail at typestry.zones.apache.org</li></ul></div>
</div>
<div class="clearer"></div>