Latest guidance (last update 31/05/2004)

[ChrisCF]

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.

[Hellfire]

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)
  Releases:
• Create tags in the CVS at every release so we can always find certain snapshots of the repostitory

[Hyronymus]

Perhaps a good idea to agree on a style of coding. I know some people aren't font of the indentions used in C++ but it does create clarity. If one doesn't do that the other one who's used to that might be searching for something for hours.

[oliver]

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 : )

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() --- */

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' : )

[Hellfire]

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:

Code: Select all

/*! some comments
 *
 * $Log$
 */

will turn into

Code: Select all

/*! some comments
 *
 * $Log$
 * Some version info
 * The comments on this commit
 */

My point here: your doxygen style commenting will be preserved by the $Log$ command

[oliver]

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).