Latest guidance (last update 31/05/2004)
Moderator: Transport Empire Moderators
Latest guidance (last update 31/05/2004)
So far, the informaiton here is entirely provisional. Comments, suggestions, anything that's left out, check below to see if it's already been mentioned.
This is to be a clean topic for potential contributors to find up-to-date information on procedures, standards, etc. This information will eventually be duplicated on the SourceForge project page once accepted.
Maybe these will end up on the SF site with linksfrom here instead, who knows
Prerequisites:
Regular contributors SHOULD (or MUST?) register accounts with SourceForge such that they might be added to the project and get CVS access.
Patches:
* Can be generated with GNU diff, available on most UNIX systems, and for Windows as part of Cygwin or possibly MinGW.
* SHOULD be generated by individuals unable to commit files to CVS, or to fix problems in release (i.e. non-CVS stuff).
* Unless it conflicts with the reason for the patch SHOULD be taken against the most recent CVS version of the file.
* SHOULD be in the "unified" format. (-u option for GNU diff)
* MUST ignore whitespace in the source files. (-b option for GNU diff)
* SHOULD be case-sensitive. (NOT using -i option for GNU diff)
* For multiple files, you SHOULD send one diff per file, unless you know how to do directory diffs properly (or I find a good way of explaining them)
Code
Someone should draft some convention for these, though they will probably appear somewhere else.
Examples:
* Source MUST be indented with each new level of scope
* Opening braces MUST be on the same line as the thing requiring it, and the closing braces MUST be on the line after the block (example to follow)
* Beginning of file SHOULD contain a list of people that worked on the file
* All source files MUST carry the project boilerplate (once it's been written)
* Use of the usual tags is encouraged (TODO, FIXME, HACK, etc. - more needed)
Releases
* Official code releases MUST be done based on the contents of CVS. You SHOULD NOT bundle up a package based on your own modifications, instead posting the diffs, or committing to CVS.
* Binary releases MUST be done based on CVS. Anonymous CVS runs on a time-delay, so this MUST be done by someone with project access.
* Anyone may release bundled versions, however, if they are not taken from current CVS, they MUST be identified as a third-party release.
Meetings
For meetings on IRC:
* A bare minimum of 96 hours' notice SHOULD be provided for the sake of catching a decent audience
* Times should be given in UTC to avoid timezone dificulties
* Saturday evenings might be preferable. Most people work in the week, but one man's evening might be another's lunch break.
* Meetings typically last more than an hour - take this into account when deciding a start time - most people interested in the project are between UTC-8 and UTC+2, which by itself is a large gap
Comments below please - pretty much anything listed above can be changed at this early stage, so suggest away.
This is to be a clean topic for potential contributors to find up-to-date information on procedures, standards, etc. This information will eventually be duplicated on the SourceForge project page once accepted.
Maybe these will end up on the SF site with linksfrom here instead, who knows
Prerequisites:
Regular contributors SHOULD (or MUST?) register accounts with SourceForge such that they might be added to the project and get CVS access.
Patches:
* Can be generated with GNU diff, available on most UNIX systems, and for Windows as part of Cygwin or possibly MinGW.
* SHOULD be generated by individuals unable to commit files to CVS, or to fix problems in release (i.e. non-CVS stuff).
* Unless it conflicts with the reason for the patch SHOULD be taken against the most recent CVS version of the file.
* SHOULD be in the "unified" format. (-u option for GNU diff)
* MUST ignore whitespace in the source files. (-b option for GNU diff)
* SHOULD be case-sensitive. (NOT using -i option for GNU diff)
* For multiple files, you SHOULD send one diff per file, unless you know how to do directory diffs properly (or I find a good way of explaining them)
Code
Someone should draft some convention for these, though they will probably appear somewhere else.
Examples:
* Source MUST be indented with each new level of scope
* Opening braces MUST be on the same line as the thing requiring it, and the closing braces MUST be on the line after the block (example to follow)
* Beginning of file SHOULD contain a list of people that worked on the file
* All source files MUST carry the project boilerplate (once it's been written)
* Use of the usual tags is encouraged (TODO, FIXME, HACK, etc. - more needed)
Releases
* Official code releases MUST be done based on the contents of CVS. You SHOULD NOT bundle up a package based on your own modifications, instead posting the diffs, or committing to CVS.
* Binary releases MUST be done based on CVS. Anonymous CVS runs on a time-delay, so this MUST be done by someone with project access.
* Anyone may release bundled versions, however, if they are not taken from current CVS, they MUST be identified as a third-party release.
Meetings
For meetings on IRC:
* A bare minimum of 96 hours' notice SHOULD be provided for the sake of catching a decent audience
* Times should be given in UTC to avoid timezone dificulties
* Saturday evenings might be preferable. Most people work in the week, but one man's evening might be another's lunch break.
* Meetings typically last more than an hour - take this into account when deciding a start time - most people interested in the project are between UTC-8 and UTC+2, which by itself is a large gap
Comments below please - pretty much anything listed above can be changed at this early stage, so suggest away.
Last edited by ChrisCF on 31 May 2004 22:26, edited 2 times in total.
Bugzilla available for use - PM for details.
-
- Transport Empire Developer
- Posts: 699
- Joined: 03 Feb 2003 09:30
- Location: Back at the office
I have some additions:
- Patches:
- Should include CVS revision number.
Code: - Each source file should include a header (todo!) containing some essential information:
- $ID$ tag (containing revision number, date and last committer)
- Perhaps (at most) three log items, for quick reference ($log$ tag)
- Create tags in the CVS at every release so we can always find certain snapshots of the repostitory
Feel free to contact me over Email! My current timezone: Europe/Amsterdam (GMT+1 or GMT+2)
[ General TE Discussion ] [ TE Development ] [ TE Coding ]
Under construction...
Code: Select all
+------------Oo.------+
| Transport Empire -> |
+---------------------+
Under construction...
Coding style draft
This is what I currerntly have and is flexible enough to be addapted. also it has doxygen style tags, something that I demand if you guys want me : )
This however is still work in progress ... im' not content with the 'blocks' etc
however this works, and it works well.
edit: things look a lot nicer with 'code' : )
Code: Select all
/*! \file <filename>.h
*
* \section generic <generic description>
*
* \section project Project information.
* Project: TEmpire\n
* \author <Original Author>
* \date yyyymmdd
* \version <version number>
*
* \section copyright Copyright
* GPL
*
* \section history Change history
* yyyymmdd <Firstname Lastname of changee>\n Initial version
*
********************************************************************/
#ifndef _<FILENAME>_H
#define _<FILENAME>_H
/*! \def EXAMPLE(x)
* \brief Brief description on EXAMPLE.
*
* Detailed description about EXAMPLE, it's use
* and further information here.
*
* \note Additional important notes about EXAMPLE here.
*/
#define EXAMPLE(x)
/*! \defgroup BOOLEANS
* \brief document #define block
*
* This block sets the TRUE and FALSE values to 0 or not 0.
*
* \note No additional notes.
*/
/*@{*/
#define FALSE 0 /*!< FALSE is 0 */
#define TRUE (!FALSE) /*!< TRUE is everything but FALSE */
/*}@*/
#else
#error "ERROR file _<FILENAME>.h multiple times included"
#endif /* --- _<FILENAME>_H --- */
===============================================
/*! \file <filename>.c
*
* \section generic <generic description>
*
* \section project Project information.
* Project: TEmpire\n
* \author <original author>\n
* \date <yyyymmdd>
* \version <version>
*
* \section copyright Copyright
* GPL.
*
* \section history Change history
* yyyymmdd <Firstname Lastname of Changee>\n Initial version
*
********************************************************************/
/* System Includes */
#include <stdio.h>
/* Library Includes */
/* Local Includes */
#include "<filename>.h" /* prototypes for this source file */
/* Local defines */
/*! \fn int example(type param, type param, ...)
* \brief this is an example function
*
* \param param this parameter is an example parameter
*
* \return if successful, the function returns something, otherwise not.
* \retval int
*/
int example(type param, type param, ...) {
int retval; /* temporary var to store return value */
reval = EXIT_FAILURE; /* set return value to EXIT_FAILURE */
return retval; /* return returnvalue */
} /* --- example() --- */
however this works, and it works well.
edit: things look a lot nicer with 'code' : )
Last edited by oliver on 08 Jul 2004 03:55, edited 1 time in total.
-
- Transport Empire Developer
- Posts: 699
- Joined: 03 Feb 2003 09:30
- Location: Back at the office
You could use CVS keywords to fill in some details automagically.
For example:
$Revision$ will fill in the revision number, e.g. $Revision: 1.23$
And changelogs can be generated from the CVS logs with:
will turn into
My point here: your doxygen style commenting will be preserved by the $Log$ command
For example:
$Revision$ will fill in the revision number, e.g. $Revision: 1.23$
And changelogs can be generated from the CVS logs with:
Code: Select all
/*! some comments
*
* $Log$
*/
Code: Select all
/*! some comments
*
* $Log$
* Some version info
* The comments on this commit
*/
Feel free to contact me over Email! My current timezone: Europe/Amsterdam (GMT+1 or GMT+2)
[ General TE Discussion ] [ TE Development ] [ TE Coding ]
Under construction...
Code: Select all
+------------Oo.------+
| Transport Empire -> |
+---------------------+
Under construction...
i'm sure there's something in doxygen to combine both these. I like it. But since i haven't used cvs al that much. all though i'm a big fan of cvs, i've heard even better things about subversion. kinda like cvs2 in a way. I think it is deffinatly worth a read. We could keep subversions 'main' branch in sync with cvs on sourceforge and all, but use subversion for our own intermediate development or something.
granted we MUST have online file versioning.
hellfire, could you check the doxygen pages about CVS support? wether it uses or something? I'd do it but i got a plane to catch tomorrow early : D
vacation! finally!!
Topic locked, information is outdated (14112006).
granted we MUST have online file versioning.
hellfire, could you check the doxygen pages about CVS support? wether it uses or something? I'd do it but i got a plane to catch tomorrow early : D
vacation! finally!!
Topic locked, information is outdated (14112006).
Who is online
Users browsing this forum: No registered users and 4 guests