[Opal-commits] web change_process.html,NONE,1.1 documentation.html,1.17,1.18

SourceForge Headquarters 1320 Columbia Street Suite 310 San Diego, CA 92101 +1 (858) 422-6466

Update of /cvsroot/opal/web
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv6629

Modified Files:
	documentation.html 
Added Files:
	change_process.html 
Log Message:
Added a document describing how to request/submit changes.

--- NEW FILE: change_process.html ---
<html xmlns:v="urn:schemas-microsoft-com:vml"
xmlns:o="urn:schemas-microsoft-com:office:office"
xmlns:w="urn:schemas-microsoft-com:office:word"
xmlns="http://www.w3.org/TR/REC-html40">

<head>
<meta http-equiv=Content-Type content="text/html; charset=windows-1252">
<meta name=ProgId content=Word.Document>
<meta name=Generator content="Microsoft Word 10">
<meta name=Originator content="Microsoft Word 10">
<link rel=File-List href="submissions_files/filelist.xml">
<link rel=Edit-Time-Data href="submissions_files/editdata.mso">
<!--[if !mso]>
<style>
v\:* {behavior:url(#default#VML);}
o\:* {behavior:url(#default#VML);}
w\:* {behavior:url(#default#VML);}
.shape {behavior:url(#default#VML);}
</style>
<![endif]-->
<title>OPAL: Open Physics Abstraction Layer</title>
<!--[if gte mso 9]><xml>
 <w:WordDocument>
  <w:Zoom>90</w:Zoom>
  <w:SpellingState>Clean</w:SpellingState>
  <w:GrammarState>Clean</w:GrammarState>
  <w:BrowserLevel>MicrosoftInternetExplorer4</w:BrowserLevel>
 </w:WordDocument>
</xml><![endif]-->
<style>
<!--
 /* Font Definitions */
 @font-face
	{font-family:"Book Antiqua";
	panose-1:2 4 6 2 5 3 5 3 3 4;
	mso-font-charset:0;
	mso-generic-font-family:roman;
	mso-font-pitch:variable;
	mso-font-signature:647 0 0 0 159 0;}
 /* Style Definitions */
 p.MsoNormal, li.MsoNormal, div.MsoNormal
	{mso-style-parent:"";
	margin:0in;
	margin-bottom:.0001pt;
	mso-pagination:widow-orphan;
	font-size:12.0pt;
	font-family:"Times New Roman";
	mso-fareast-font-family:"Times New Roman";
	color:white;}
a:link, span.MsoHyperlink
	{color:#3366FF;
	text-decoration:underline;
	text-underline:single;}
a:visited, span.MsoHyperlinkFollowed
	{color:#000066;
	text-decoration:underline;
	text-underline:single;}
span.SpellE
	{mso-style-name:"";
	mso-spl-e:yes;}
span.GramE
	{mso-style-name:"";
	mso-gram-e:yes;}
@page Section1
	{size:8.5in 11.0in;
	margin:1.0in 1.25in 1.0in 1.25in;
	mso-header-margin:.5in;
	mso-footer-margin:.5in;
	mso-paper-source:0;}
div.Section1
	{page:Section1;}
-->
</style>
<!--[if gte mso 10]>
<style>
 /* Style Definitions */
 table.MsoNormalTable
	{mso-style-name:"Table Normal";
	mso-tstyle-rowband-size:0;
	mso-tstyle-colband-size:0;
	mso-style-noshow:yes;
	mso-style-parent:"";
	mso-padding-alt:0in 5.4pt 0in 5.4pt;
	mso-para-margin:0in;
	mso-para-margin-bottom:.0001pt;
	mso-pagination:widow-orphan;
	font-size:10.0pt;
	font-family:"Times New Roman";}
</style>
<![endif]--><!--[if gte mso 9]><xml>
 <o:shapedefaults v:ext="edit" spidmax="5122"/>
</xml><![endif]--><!--[if gte mso 9]><xml>
 <o:shapelayout v:ext="edit">
  <o:idmap v:ext="edit" data="1"/>
 </o:shapelayout></xml><![endif]-->
</head>

<body bgcolor=white lang=EN-US link="#3366FF" vlink="#000066" style='tab-interval:
.5in'>

<div class=Section1>

<table class=MsoNormalTable border=0 cellspacing=0 cellpadding=0 width="95%"
 style='width:95.58%;mso-cellspacing:0in;mso-padding-alt:0in 0in 0in 0in'>
 <tr style='mso-yfti-irow:0;mso-yfti-lastrow:yes'>
 <td width=1295 valign=top style='width:777.0pt;padding:7.5pt 7.5pt 7.5pt 7.5pt'>
 &nbsp;
 &nbsp;
 <img width=534 height=129
 id="_x0000_i1025" src="files/opal_logo.jpg">
 &nbsp;
 &nbsp;
 Bug Reports,
 Feature Requests, Patch Submissions, OPAL Design Philosophy, and Coding
 Conventions
 &nbsp;
 &nbsp;
 This page
 is a reference for those people wanting to submit bug reports, feature
 requests, or patches submissions to the OPAL source code.  Most of these processes are handled via SourceForge trackers (see Document E03 of the SourceForge Site Docs for more information on tracker
 system, or click <a
 href="http://sourceforge.net/docman/display_doc.php?docid=24202&amp;group_id=1">here</a>
 for the current link to this document). 
 This page also describes OPALs design
 philosophy and coding conventions for people writing source code patches.<o:p></o:p>
 &nbsp;<o:p></o:p>
 Bug Reports<o:p></o:p>
 To
 submit a bug report, visit the Bugs link on the SourceForge
 project page.  Submit a detailed
 description of the problem.<o:p></o:p>
 <o:p>&nbsp;</o:p>
 Feature
 Requests<o:p></o:p>
 To
 submit a bug report, visit the RFE (request for enhancement) link on the SourceForge project page. 
 Submit a detailed description of the feature you wish to be added and
 your reasoning for why this feature has mass appeal.<o:p></o:p>
 <o:p>&nbsp;</o:p>
 Patch
 Submission<o:p></o:p>
 1. If you have an idea for an
 OPAL patch (e.g. bug fix, additional class member functions, support for a
 physics engine, etc.) that you would like to implement and submit, first
 discuss it with others in the forum to see if it would be useful for a lot of
 people.  Some ideas for patches will
 not be useful for much of the OPAL community and will not be considered (but,
 of course, you can always make modifications to your own version of
 OPAL).  The OPAL development team makes
 the final decision of whether a patch gets applied or not, so it would be wise
 to discuss your idea on the forum with one of the developers before starting
 your implementation.<o:p></o:p>
 <o:p>&nbsp;</o:p>
 2. Implement the patch
 (following the OPAL design philosophy and coding conventions described below)
 and test it thoroughly.<o:p></o:p>
 <o:p>&nbsp;</o:p>
 3. Submit the patch via the
 Patches link on the SourceForge project
 page.  &lt;TODO: what format?  all changed/new
 files, or just a CVS diff?&gt;<o:p></o:p>
 <o:p>&nbsp;</o:p>
 Design
 Philosophy<o:p></o:p>
 This
 section contains a short description of the overall design philosophy.  Remember, when in doubt,
 look at the existing source code.<o:p></o:p>
 <o:p>&nbsp;</o:p>
 The
 Simulator is a factory and container for all other objects, such as Solids,
 Joints, Motors, and Sensors.<o:p></o:p>
 <o:p>&nbsp;</o:p>
 All
 parts of the base OPAL code must be totally independent of the specific
 physics engines.<o:p></o:p>
 <o:p>&nbsp;</o:p>
 Supported
 physics engines should be cross-platform, with support for at least Linux and
 Win32.<o:p></o:p>
 <o:p>&nbsp;</o:p>
 Every
 main object has an internal Data class that defines the properties of the
 object.  This makes it easy to copy,
 save, and load simulation 
 states.  Thus, all information about an
 object needed to restore the state of the simulation should be added to that
 object's Data class.  All variables in
 an object's Data class should be handled by the BlueprintManager
 when loading/saving XML files.<o:p></o:p>
 <o:p>&nbsp;</o:p>
 Coding
 Conventions<o:p></o:p>
 This
 section contains a set of coding conventions used in OPAL.  Remember, when in doubt,
 look at the existing source code.<o:p></o:p>
 <o:p>&nbsp;</o:p>
 General<o:p></o:p>
 No
 space tabs!  Use actual tabs for
 indentation, not spaces.<o:p></o:p>
 
 All curly braces should be on new lines (even for one-line if
 statements).  For example:<o:p></o:p>
 if(test) 
 {<o:p></o:p>
     x = 5; 
 } 
 
 Keep each line to 80 characters or fewer. 
 
 Return types should be on same line as the function name (unless return type
 is long enough to hit the 80 character limit).  <o:p></o:p>
 
 Every {} block is indented by one tab, including namespaces.  For example: 
 namespace opal 
 { 
     if(condition) 
 &nbsp; &nbsp; { 
 &nbsp; &nbsp; &nbsp; &nbsp; // code 
 &nbsp; &nbsp; } 
 }<o:p></o:p>
 <o:p>&nbsp;</o:p>
 Capitalization Styles and
 Naming Conventions<o:p></o:p>
 Pascal
 casing capitalizes the first letter of each word (e.g.&nbsp;FooBar)<o:p></o:p>
 Camel
 casing capitalizes the first letter of each word except the first one (e.g. fooBar)<o:p></o:p>
 
 Classes &nbsp;- &nbsp;Pascal casing 
 Local variables Camel casing 
 Member variables Pascal casing with m prefix 
 Namespaces Camel casing 
 Functions Camel casing 
 Function arguments Camel casing 
 Internal Functions - Camel casing with internal_ prefix (an internal function
 is a class member function that needs to be publicly accessible but should
 not be accessed through the API)<o:p></o:p>
 <o:p>&nbsp;</o:p>
 All
 get/set functions begin with get and set except get functions that return
 a boolean, in which case the name should start with
 is.<o:p></o:p>
 <o:p>&nbsp;</o:p>
 Source Code Documentation<o:p></o:p>
 It is
 important that the source code is well-documented in two ways: 1) all
 components of the public API should have a detailed description of their
 function; this information gets automatically incorporated into the Doxygen-generated API documentation, and 2) all
 potentially confusing source code should be explained in the code.<o:p></o:p>
 <o:p>&nbsp;</o:p>
 Use Doxygen triple slash commenting style (e.g. /// Some
 comment) in front of all class, function, variable, enum,
 namespace, etc. definitions.  Otherwise
 use all double slash comments (e.g. // Some comment), not block comments
 (e.g. /* Some comment */).  Most source
 code editors have built-in functions for selecting and commenting out chunks
 of code, and they usually use double slash comments. <o:p></o:p>
 </td>
 </tr>
</table>

<p class=MsoNormal align=center style='margin-bottom:12.0pt;text-align:center'><span
style='font-size:10.0pt;font-family:"Book Antiqua";color:#333333'>&nbsp;</span></p>

<p class=MsoNormal align=center style='margin-bottom:12.0pt;text-align:center'><span
style='font-size:8.0pt;font-family:"Book Antiqua";color:black'>OPAL is
Copyright © 2004-2005 Alan Fischer, Andres Reinot, and Tyler Streeter</span></p>

</div>

</body>

</html>

Index: documentation.html
===================================================================
RCS file: /cvsroot/opal/web/documentation.html,v
retrieving revision 1.17
retrieving revision 1.18
diff -C2 -d -r1.17 -r1.18
*** documentation.html	4 Jun 2005 19:30:27 -0000	1.17
--- documentation.html	18 Jun 2005 17:19:37 -0000	1.18
***************
*** 25,39 ****
    <o:Author>Tyler Streeter</o:Author>
    <o:LastAuthor>Tyler Streeter</o:LastAuthor>
!   <o:Revision>111</o:Revision>
!   <o:TotalTime>112</o:TotalTime>
    <o:Created>2004-06-05T15:20:00Z</o:Created>
!   <o:LastSaved>2005-06-04T19:28:00Z</o:LastSaved>
!   <o:Pages>1</o:Pages>
!   <o:Words>325</o:Words>
!   <o:Characters>1858</o:Characters>
    <o:Company>none</o:Company>
!   <o:Lines>15</o:Lines>
    <o:Paragraphs>4</o:Paragraphs>
!   <o:CharactersWithSpaces>2179</o:CharactersWithSpaces>
    <o:Version>10.6714</o:Version>
   </o:DocumentProperties>
--- 25,39 ----
    <o:Author>Tyler Streeter</o:Author>
    <o:LastAuthor>Tyler Streeter</o:LastAuthor>
!   <o:Revision>123</o:Revision>
!   <o:TotalTime>125</o:TotalTime>
    <o:Created>2004-06-05T15:20:00Z</o:Created>
!   <o:LastSaved>2005-06-18T17:17:00Z</o:LastSaved>
!   <o:Pages>2</o:Pages>
!   <o:Words>373</o:Words>
!   <o:Characters>2127</o:Characters>
    <o:Company>none</o:Company>
!   <o:Lines>17</o:Lines>
    <o:Paragraphs>4</o:Paragraphs>
!   <o:CharactersWithSpaces>2496</o:CharactersWithSpaces>
    <o:Version>10.6714</o:Version>
   </o:DocumentProperties>
***************
*** 74,77 ****
--- 74,80 ----
  	text-decoration:underline;
  	text-underline:single;}
+ span.SpellE
+ 	{mso-style-name:"";
+ 	mso-spl-e:yes;}
  @page Section1
  	{size:8.5in 11.0in;
***************
*** 101,105 ****
  </style>
  <![endif]--><!--[if gte mso 9]><xml>
!  <o:shapedefaults v:ext="edit" spidmax="65538">
    <o:colormenu v:ext="edit" fillcolor="white"/>
   </o:shapedefaults></xml><![endif]--><!--[if gte mso 9]><xml>
--- 104,108 ----
  </style>
  <![endif]--><!--[if gte mso 9]><xml>
!  <o:shapedefaults v:ext="edit" spidmax="67586">
    <o:colormenu v:ext="edit" fillcolor="white"/>
   </o:shapedefaults></xml><![endif]--><!--[if gte mso 9]><xml>
***************
*** 187,193 ****
    through the documentation in the following order: 1) overview, 2) tutorials,
    3) API reference.<span style='mso-spacerun:yes'>  </span>The overview and
!   tutorials do not cover everything; they exist to help you learn to use OPAL
!   quickly.<span style='mso-spacerun:yes'>  </span>Consult the API reference for
!   more details.<o:p></o:p></span></p>
    <p class=MsoNormal><span style='font-family:"Book Antiqua";color:black'><o:p>&nbsp;</o:p></span></p>
    <p class=MsoNormal><span style='font-size:14.0pt;font-family:"Book Antiqua";
--- 190,196 ----
    through the documentation in the following order: 1) overview, 2) tutorials,
    3) API reference.<span style='mso-spacerun:yes'>  </span>The overview and
!   tutorials do not cover everything; they exist to help you learn to use the
!   basics quickly.<span style='mso-spacerun:yes'>  </span>Consult the API reference
!   for a more detailed description.<o:p></o:p></span></p>
    <p class=MsoNormal><span style='font-family:"Book Antiqua";color:black'><o:p>&nbsp;</o:p></span></p>
    <p class=MsoNormal><span style='font-size:14.0pt;font-family:"Book Antiqua";
***************
*** 242,249 ****
    style='font-family:"Book Antiqua";color:black'>: a detailed description of
    everything in OPAL.<span style='mso-spacerun:yes'>  </span>If a particular
!   concept isnt discussed in the overview or tutorials, check here.</span><span
!   style='font-family:"Book Antiqua";mso-bidi-font-family:Arial;color:black'><o:p></o:p></span></p>
!   <p class=MsoNormal><span style='font-family:"Book Antiqua";mso-bidi-font-family:
!   Arial;color:black'><o:p>&nbsp;</o:p></span></p>
    </td>
   </tr>
--- 245,257 ----
    style='font-family:"Book Antiqua";color:black'>: a detailed description of
    everything in OPAL.<span style='mso-spacerun:yes'>  </span>If a particular
!   concept isnt discussed in the overview or tutorials, check here.<o:p></o:p></span></p>
!   <p class=MsoNormal><span style='font-family:"Book Antiqua";color:black'><o:p>&nbsp;</o:p></span></p>
!   <p class=MsoNormal><span style='font-size:14.0pt;font-family:"Book Antiqua";
!   color:black'><a href="change_process.html">Change Process</a></span><span
!   style='font-family:"Book Antiqua";color:black'>: contains information for
!   people wanting to request/submit changes to OPAL via bug reports, feature
!   requests, or actual patch submissions.<span style='mso-spacerun:yes'> 
!   </span>Also contains information on <span class=SpellE>OPALs</span> design
!   philosophy and coding conventions for those writing patches.</span><o:p></o:p></p>
    </td>
   </tr>