<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html><head><meta http-equiv="Content-Type" content="text/html;charset=iso-8859-1">
<title>GearBox Project</title>
<link rel="icon" href="gbx_icon_cardbox_sky.png" type="image/png">
<link rel="shortcut icon" href="gbx_icon_cardbox_sky.png" type="image/png">
<link href="doxygen.css" rel="stylesheet" type="text/css">
<link href="tabs.css" rel="stylesheet" type="text/css">
<!-- Google Analytics -->
<script type="text/javascript">
var gaJsHost = (("https:" == document.location.protocol) ? "https://ssl." : "http://www.");
document.write(unescape("%3Cscript src='" + gaJsHost + "google-analytics.com/ga.js' type='text/javascript'%3E%3C/script%3E"));
</script>
<script type="text/javascript">
var pageTracker = _gat._getTracker("UA-3583782-1");
pageTracker._initData();
pageTracker._trackPageview();
</script>
<!-- Returning you to your regular programming -->
</head><body>
<!-- Header -->
<table border="0" cellspacing="0" cellpadding="0">
<tr><!-- create row -->
<!-- spacer cell -->
<!-- #CC CC CC -->
<td rowspan="1" colspan="1" bgcolor="#EEEEEE"> </td>
<!-- menu cell -->
<td width="170" rowspan="1" colspan="1" align="left" valign="top" bgcolor="#EEEEEE">
<p> </p>
<p align="center"><a href="index.html"><img src="gbx_logo_cardbox_sky_150x150.png"></a></p><br>
<strong>INTRODUCTION</strong><br>
<strong><a href="gbx_doc_overview.html" style="text-decoration:none">Overview</a></strong><br>
<strong><a href="gbx_doc_getting.html" style="text-decoration:none">Download and Install</a></strong><br>
<!-- <strong><a href="gbx_doc_quickstart.html" style="text-decoration:none">Quick Start</a></strong><br> -->
<strong><a href="gbx_doc_documentation.html" style="text-decoration:none">Documentation</a></strong><br>
<strong><a href="gbx_doc_publications.html" style="text-decoration:none">Publications</a></strong><br>
<br>
<strong>REPOSITORY</strong><br>
<strong><a href="group__gbx__libs.html" style="text-decoration:none">Libraries</a></strong><br>
<!-- <strong><a href="group__gbx__utils.html" style="text-decoration:none">Utilities</a></strong><br> -->
<br>
<strong>DEVELOPER</strong><br>
<!--<strong><a href="gbx_doc_tutorials.html" style="text-decoration:none">Tutorials</a></strong><br>
<strong><a href="group__gbx__examples.html" style="text-decoration:none">Examples</a></strong><br>-->
<strong><a href="gbx_doc_devguide.html" style="text-decoration:none">Dev Guide</a></strong><br>
<!--
<strong><a href="gbx_doc_faq.html" style="text-decoration:none">FAQ</a></strong><br>
-->
<strong><a href="http://cdash.acfr.usyd.edu.au/index.php?project=Gearbox" style="text-decoration:none">Dashboard</a></strong><br>
<!--<strong><a href="http://wiki2.cas.edu.au/orca">Wiki</a></strong><br>
login/pass: orca/orca<br>-->
<br>
<strong>PEOPLE</strong><br>
<strong><a href="gbx_doc_contributors.html" style="text-decoration:none">Contributors</a></strong><br>
<strong><a href="gbx_doc_users.html" style="text-decoration:none">Users</a></strong><br>
<br>
<a href="http://sourceforge.net"><img src="http://sourceforge.net/sflogo.php?group_id=216468&type=2" width="125" height="37" border="0" alt="SourceForge.net Logo" /></a><br>
<strong><a href="http://sourceforge.net/projects/gearbox">Project</a></strong><br>
<strong><a href="http://sourceforge.net/project/showfiles.php?group_id=216468">Download</a></strong><br>
<!--<strong><a href="http://sourceforge.net/tracker/?group_id=216468">Bugs/Feedback</a></strong><br>-->
<strong><a href="http://sourceforge.net/mail/?group_id=216468">Mailing lists</a></strong></p>
<p> </p>
</td><!-- /menu cell -->
<!-- one grey spacer cells -->
<td rowspan="1" colspan="1" bgcolor="#EEEEEE"> </td>
<!-- one white spacer cells -->
<td rowspan="1" colspan="1"> </td>
<!-- main content cell -->
<td rowspan="1" colspan="1" align="left" valign="top">
<!-- Generated by Doxygen 1.6.2-20100208 -->
<div class="navigation" id="top">
<div class="tabs">
<ul>
<li><a href="index.html"><span>Main Page</span></a></li>
<li class="current"><a href="pages.html"><span>Related Pages</span></a></li>
<li><a href="modules.html"><span>Modules</span></a></li>
<li><a href="namespaces.html"><span>Namespaces</span></a></li>
<li><a href="annotated.html"><span>Classes</span></a></li>
<li><a href="files.html"><span>Files</span></a></li>
<li><a href="dirs.html"><span>Directories</span></a></li>
</ul>
</div>
</div>
<div class="contents">
<h1><a class="anchor" id="gbx_doc_principles">Principles of Project Operation </a></h1><p>We hope that this project will attract a diverse group of developers. If this happens we think that a clear set of written down rules would help to avoid misunderstandings.</p>
<p>The rules on the pages are brief. We also maintain a page with <a class="el" href="gbx__doc__practices.html">more practical instructions and a guide to common practices</a>.</p>
<h2><a class="anchor" id="gbx_doc_principles_toc">
Table of contents</a></h2>
<ul>
<li><a class="el" href="gbx__doc__principles.html#gbx_doc_principles_tools">1. Tools</a></li>
<li><a class="el" href="gbx__doc__principles.html#gbx_doc_principles_operation">2. Project Operation</a><ul>
<li><a class="el" href="gbx__doc__principles.html#gbx_doc_principles_operation_lifecycle">2.1 Source code life cycle</a><ul>
<li><a class="el" href="gbx__doc__principles.html#gbx_doc_principles_operation_lifecycle_submit">2.1.1 Criteria for submission</a></li>
<li><a class="el" href="gbx__doc__principles.html#gbx_doc_principles_operation_lifecycle_accept">2.1.2 Criteria for acceptance</a></li>
<li><a class="el" href="gbx__doc__principles.html#gbx_doc_principles_operation_lifecycle_warn">2.1.3 Criteria for a warning</a></li>
<li><a class="el" href="gbx__doc__principles.html#gbx_doc_principles_operation_lifecycle_disable">2.1.4 Criteria for disabling</a></li>
<li><a class="el" href="gbx__doc__principles.html#gbx_doc_principles_operation_lifecycle_retire">2.1.5 Criteria for retirement</a></li>
</ul>
</li>
<li><a class="el" href="gbx__doc__principles.html#gbx_doc_principles_operation_release">2.2 Release of source code</a></li>
<li><a class="el" href="gbx__doc__principles.html#gbx_doc_principles_operation_ownership">2.3 Ownership of source code</a></li>
</ul>
</li>
<li><a class="el" href="gbx__doc__principles.html#gbx_doc_principles_freedoms">3. Freedoms</a></li>
<li><a class="el" href="gbx__doc__principles.html#gbx_doc_principles_style">Appendix A. Programming Style Description.</a></li>
</ul>
<h2><a class="anchor" id="gbx_doc_principles_tools">
1. Tools</a></h2>
<dl class="user"><dt><b>Build system</b></dt><dd></dd></dl>
<p>CMake</p>
<dl class="user"><dt><b>Revision control system</b></dt><dd></dd></dl>
<p>Subversion</p>
<dl class="user"><dt><b>Unit test system</b></dt><dd></dd></dl>
<p>CTest</p>
<dl class="user"><dt><b>Documentation</b></dt><dd></dd></dl>
<p>Doxygen</p>
<dl class="user"><dt><b>Hosting service</b></dt><dd></dd></dl>
<p>SourceForge</p>
<dl class="user"><dt><b>Bug Tracking</b></dt><dd></dd></dl>
<p>Trac</p>
<h2><a class="anchor" id="gbx_doc_principles_operation">
2. Project Operation</a></h2>
<h3><a class="anchor" id="gbx_doc_principles_operation_lifecycle">
2.1 Source code life cycle</a></h3>
<div align="center">
<img src="gbx_src_life_cycle.png" alt="gbx_src_life_cycle.png"/>
</div>
<h3><a class="anchor" id="gbx_doc_principles_operation_lifecycle_submit">
2.1.1 Criteria for submission</a></h3>
<dl class="user"><dt><b>Relevance</b></dt><dd></dd></dl>
<p>Any reusable software related to robotics. Emphasis is placed on algorithm and driver implementations. Integration frameworks are generally discouraged. Relevance of a particular library is determined through mailing list discussion.</p>
<dl class="user"><dt><b>License</b></dt><dd></dd></dl>
<p>Must specify <b>an</b> open source license.</p>
<dl class="user"><dt><b>Copyright</b></dt><dd></dd></dl>
<p>Must specify ownership.</p>
<h3><a class="anchor" id="gbx_doc_principles_operation_lifecycle_accept">
2.1.2 Criteria for acceptance</a></h3>
<dl class="user"><dt><b>Documentation</b></dt><dd></dd></dl>
<p>Sufficient to be useful, depends on the complexity of software, determined by peer review (at least 1 reviewer) and a public discussion on the mailing list.</p>
<dl class="user"><dt><b>Tests and sample code</b></dt><dd></dd></dl>
<p>Sufficient to be useful, depends on software, determined by peer review.</p>
<dl class="user"><dt><b>Programming style</b></dt><dd></dd></dl>
<p>Must name a known style, or describe a style (see <a class="el" href="gbx__doc__principles.html#gbx_doc_principles_style">Appendix A</a>), and adhere to it.</p>
<dl class="user"><dt><b>Compilation</b></dt><dd></dd></dl>
<p>Must compile without warnings (with -Wall) on all supported platforms with all supported compilers.</p>
<dl class="user"><dt><b>Operation</b></dt><dd></dd></dl>
<p>Libraries must operate (within reason) as described by the documentation. Reviewers of hardware drivers are encouraged to have access to hardware where feasible.</p>
<h3><a class="anchor" id="gbx_doc_principles_operation_lifecycle_warn">
2.1.3 Criteria for a warning</a></h3>
<p>Failure of any in <a class="el" href="gbx__doc__principles.html#gbx_doc_principles_operation_lifecycle_accept">2.1.2 Criteria for acceptance</a>.</p>
<h3><a class="anchor" id="gbx_doc_principles_operation_lifecycle_disable">
2.1.4 Criteria for disabling</a></h3>
<dl class="user"><dt><b>Compilation</b></dt><dd></dd></dl>
<p>Fails to compile on any one of the supported platforms/complilers (as specified by the library developer) or does not gracefully handle one of the platforms/compilers specified as supported by Gearbox but not supported by that library - will be disabled immediatly in SVN and in any following releases until fixed</p>
<h3><a class="anchor" id="gbx_doc_principles_operation_lifecycle_retire">
2.1.5 Criteria for retirement</a></h3>
<dl class="user"><dt><b>Compilation</b></dt><dd></dd></dl>
<p>Fails for 2 months since disabling to compile on any one of the supported platforms/complilers (as specified by the library developer) or does not gracefully handle one of the platforms/compilers specified as supported by Gearbox but not supported by that library - will be moved to graveyard at the end of the 2nd month.</p>
<dl class="user"><dt><b>Other</b></dt><dd></dd></dl>
<p>Failure of any <a class="el" href="gbx__doc__principles.html#gbx_doc_principles_operation_lifecycle_accept">2.1.2 Criteria for acceptance</a> for 3 months after warning.</p>
<h3><a class="anchor" id="gbx_doc_principles_operation_release">
2.2 Release of source code</a></h3>
<p>Regular frequent releases every 1.5-3 months.</p>
<h3><a class="anchor" id="gbx_doc_principles_operation_ownership">
2.3 Ownership of source code</a></h3>
<p>Copyright belongs to authors and major contributors. The copyright is recorded in a comment block at the top of every source file. It is up to the current copyright holders to distinguish between "major" and "minor" contributions.</p>
<h2><a class="anchor" id="gbx_doc_principles_freedoms">
3. Freedoms</a></h2>
<p>Aside from complying with Sec.2, the designer of every module within the project is not constrained in any way. We specifically mention several important freedoms:</p>
<ul>
<li>OS, compiler, programming language. New contributor's responsibility is to make sure that the new addition does not break the existing code.</li>
<li>code design, e.g. whether or not to use C++ exceptions.</li>
<li>dependencies</li>
<li>data types used by libraries.</li>
</ul>
<h2><a class="anchor" id="gbx_doc_principles_style">
Appendix A. Programming Style Description.</a></h2>
<p>In the case of not using a well-known, named style, contributors must describe the programming style in sufficient detail for others to be able to adhere to it (assuming, of course, that others are also capable of looking at the code for details). An example of what is necessary for C++ is given below.</p>
<dl class="user"><dt><b>Naming conventions</b></dt><dd></dd></dl>
<ul>
<li>variables, member variables, classes, structs, namespaces</li>
<li>functions, member functions</li>
<li>#defines, enums</li>
<li>filenames</li>
<li>API usage style</li>
</ul>
<dl class="user"><dt><b>Units and coordinate systems</b></dt><dd></dd></dl>
<p>If applicable (needless to say that the units and CS's of the API must be documented separately, this applies to the code itself.) </p>
</div>
</td>
<td colspan="1"> </td>
</tr>
</table>
<!-- end of table -->
<hr size="1"><address style="align: right;"><small>Generated for GearBox by
<a href="http://www.doxygen.org/index.html">
<img src="doxygen.png" alt="doxygen" align="middle" border="0"></a> 1.4.5 </small></address>
</body>
</html>
