Adding development process documentation

doc/doxygen/additional_doc/code_style.dox

@@ -1,5 +1,5 @@
 /*!
-\page new_code_style Coding Style
+\page code_style Coding Style
 
 \section general_comments General comments
 
@@ -38,8 +38,8 @@
 
 - IMPLICIT NONE must be used in all modules and programs.
 - INTENT(IN|OUT|INOUT) must be used for all dummy arguments including pointers. 
-- If there is just a single statement following an IF clause use the inline form of the IF statement and do not use THEN and ENDIF.
-- For dummy array arguments the dimension qualifier should be with the array name i.e., use INTEGER(INTG) :: FRED(N) rather than INTEGER(INTG), DIMENSION(N) :: FRED.
+- If there is just a single statement following an IF clause use the inline form of the IF statement and do not use THEN and END IF.
+- For dummy array arguments the dimension qualifier should be with the array name i.e., use INTEGER(INTG) :: fred(N) rather than INTEGER(INTG), DIMENSION(N) :: fred.
 - always name program units, types and interfaces and use the corresponding END PROGRAM, END SUBROUTINE, END MODULE, END TYPE, END INTERFACE etc. etc. 
 - Never use a Fortran keyword as a variable name. Never use the name of an intrinsic function as the name for a user-defined function.
 - Use :: after the declaration part of a variable, even if there are no attributes.
@@ -52,8 +52,8 @@
 - Use assumed shape arrays whereever possible i.e., A(:) instead of A(*) for array arguments.
 - No space between the conditional statement and condition i.e. IF( rather than IF (, WHILE( rather than WHILE ( etc.
 - All multiword Fortran statements should have a space i.e., END IF, ELSE IF, END DO, END SELECT etc.
-- For read/write/print statement, avoid the comma before the data variable e.g., use READ(FILE_ID, CHAR(DP_FMT), IOSTAT=IOS) REAL_DATA(1:LEN_OF_DATA) instead of READ(FILE_ID, CHAR(DP_FMT), IOSTAT=IOS), REAL_DATA(1:LEN_OF_DATA)
-- In IF/WHILE statement, do not use full logical expressions e.g., use IF(SOMEVALUE) or IF(.NOT.SOMEVALUE) instead of IF(SOMEVALUE==.TRUE.) or IF(SOMEVALUE==.FALSE.)
+- For read/write/print statement, avoid the comma before the data variable e.g., use READ(filedId, CHAR(dpFmt), IOSTAT=ios) realData(1:lenOfData) instead of READ(fileId, CHAR(dpFmt), IOSTAT=ios), realData(1:lenOfData)
+- In IF/WHILE statement, do not use full logical expressions e.g., use IF(someValue) or IF(.NOT.someValue) instead of IF(someValue==.TRUE.) or IF(someValue==.FALSE.)
 - Do not use multiple statements in one line. Use separate lines for each statement.
 - An INTERFACE block must be used for all SUBROUTINES/FUNCTIONS that are not otherwise automatically available via a USE statement and MODULEs.
 - SELECT CASE statements must always have a CASE DEFAULT clause. If there is no default action include the CASE DEFAULT and put !Do nothing as a comment.
@@ -63,7 +63,7 @@
 - COMMON blocks - use MODULES instead
 - EQUIVALENCE 
 - Assigned and computed GOTOs - use SELECT CASE statements
-- Artihmetic IF statements - use a full IF, ELSEIF, ELSE, ENDIF or SELECT CASE instead. 
+- Artihmetic IF statements - use a full IF, ELSE IF, ELSE, END IF or SELECT CASE instead. 
 - GOTO and CONTINUE - use IF, CASE, DO WHILE, EXIT and CYCLE instead.
 - PAUSE statements
 - ENTRY statements
@@ -110,8 +110,8 @@
 - All TYPES shall have _Initialise and _Finalise routines for construction and destruction.
 - Within a module all named constants and procedure names should be prefixed by a name indicating that module so as to maintain a namespace.
 - Use lower case for loop variables.
-- Use dof/node hierarchy consistently in subroutine calls. i.e., version_number,derivative_number,node_number,component_number,variable_number instead of reverse order.
-- For subroutine arguments the input variables should be first, then the output variables and then the error variables. Variables should, in general, be arranged alphabetically unless another coding convention dictates otherwise (.e.g, dof/nod hierarchy).
+- Use dof/node hierarchy consistently in subroutine calls. i.e., versionNumber,derivativeNumber,nodeNumber,componentNumber,variableNumber instead of reverse order.
+- For subroutine arguments the input variables should be first, then the output variables and then the error variables. Variables should, in general, be arranged alphabetically unless another coding convention dictates otherwise (.e.g, DOF/node hierarchy).
 - If variables are out of range then any error messages should try to provide information on what variables are out of range and what the values are.
 - Do not use temporary write statements for debugging or other purposes. Use diagnostics. If the values of the variables are of importance to you for working out how the routine works then they will be of importance to others at a later time and thus time should be taken to provide detailed diagnostic output. 
 - For routines that return information (i.e., get routines) use SUBROUTINEs instead of FUNCTIONs. The result should be returned in memory supplied by the calling routine. The size of the supplied memory should be checked to ensure that it is large enough to hold the result. 
@@ -121,7 +121,7 @@
 
 \subsection for_discussion2 For discussion
 
-- The use of guard clauses e.g., rather than IF(CHECK) THEN .. ELSE Error ENDIF use IF(.NOT.CHECK) Error
+- The use of guard clauses e.g., rather than IF(check) THEN .. ELSE Error END IF use IF(.NOT.check) Error
 - ASSERT macros????
 
 \section good_practice Good practice

doc/doxygen/additional_doc/development_process.dox

@@ -0,0 +1,49 @@
+ /*!
+\page development OpenCMISS-Iron Development Process
+
+This page details the development process that should be followed for OpenCMISS-Iron.
+
+\section before_start_development Before you begin
+
+Before you begin you should:
+- Familiarise yourself with the latest coding style (see \ref code_style)
+- Study the git workflow (see http://sourceforge.net/apps/mediawiki/opencmiss/index.php?title=Git_Workflow)
+\todo In the setup document add info about creating a post-commit hook.
+
+\section development_process Development Process
+
+The development process that should be followed is:
+1. Discuss your problem and proposal either at the OpenCMISS-Iron meeting or on the mailing list. 
+2. Create a tracker item for your work.
+3. Create a git branch for your work and check it out.
+4. Commit and push your changes often to your repository with appropriate commit messages (including the tracker number with a “tracker item” before the number so that the post-commit hook will add a link to the tracker). Commit small and often!
+5. Write a test example if possible or practicable.
+
+\section committing_process Committing Process
+
+The committing process that should be followed is:
+1. The commit message format should be summary, blank line, tracker item number, blank line, more detail.
+2. Update the tracker often so as to reflect the progress and problems faced. Make the tracker tell the story of the change! Some of this will be done by the post-commit hook but add extra comments if required.
+3. Run tests on your changes and run all the examples on buildbot to make sure that they all pass. Include a buildbot link to the build in the tracker. 
+4. Make sure all compiler warnings are addressed.
+5. When you are ready to have your code merged back into the trunk create a “pull request” for your changes. The tracker item should be changed to “resolved/fixed”.
+6. Approach or nominate people to review your changes and place this information in the tracker. 
+
+\section review_process Review Process
+
+The review process that should be followed is:
+1. Once you have accepted the role of reviewer change the tracker to assign it to yourself.
+2. Go through the code and make comments on the GitHub pull request on any required changes and corrections and/or questions about the code. 
+3. You should review coding style, code clarity, existence of tests, implementation method, documentation, OpenCMISS-Iron notes. 
+4. During the review the commit messages should state what has changed and be independent of the review comments. 
+5. The reviewer should ensure that the examples run using the buildbot sandbox.
+6. When the review has finished and the code is ready to be pulled into the main repository the reviewer should add a comment to this effect in GitHub and the tracker. The code reviewer should change the tracker status to “verified/fixed”.
+7. Once the tracker item has been changed to verified/fixed and the repository manager is happy with the process they will pull the code into the repository and changed the tracker item to “closed/fixed”.	
+
+\section collaboration_process Collaboration Process
+
+The collaboration process that should be followed is:
+1. The collaboration process should be very similar to the commit process above (with the exception of changing the tracker status).
+2. If developers are working particularly close on an item git and GitHub allow for other modes of collaboration. A few of these include:
+  -  Set up each of your collaborators' repositories as a remote and then merge their changes into your repository.
+  -  Give collaborators access to your repository so that they can push changes directly.

doc/doxygen/additional_doc/installation.dox

@@ -392,8 +392,9 @@ You may specify the following options to the build:
 - USEFIELDML=(false|true): to use FieldML or not
 
 3. Execute the example:
-You may specify the arguments to execute the example, e.g.
-\code ./bin/x86_64-linux/mpich2/gnu_4.4/LaplaceExample-debug 4 4 4 1 \endcode
+You may specify the arguments to execute the example, e.g. For a 64-bit linux using MPICH2 and GNU 4.4 compilers you could type
+\code ./bin/x86_64-linux/mpich2/gnu_4.4/FortranExample-debug 4 4 4 1 \endcode
+For other versions of MPI or compiler please adjust the path to the FortranExample-debug example appropriately.
 
 4. Execute the example with mpi:
 To execute the example with mpi running on two computational nodes:

doc/doxygen/additional_doc/pageslist.dox

@@ -3,11 +3,11 @@
 - \subpage introduction
 - \subpage concepts
 - \subpage installation
+- \subpage code_style 
+- \subpage development
 - \subpage object_interface
 - \subpage local-examples
 - \subpage library_commands  
-- \subpage code_style 
-- \subpage new_code_style 
 - \subpage get_updated
 - \subpage tools
 - \subpage profiling_with_TAU