README.Maint

README.Maint - information for nc6 maintainers
--------------------------------------------------------------

$Id: README.Maint,v 1.12 2003-04-20 09:30:58 chris Exp $


Source layout
-------------

/		- build files (configure, Makefile.am, etc)
/config		- autoconf macros
/src		- all source code
/docs		- documentation, man pages, etc


Prerequisites
-------------

Netcat6 uses autoconf and automake for its build system.  Currently building
the configure scripts requires autoconf version >= 2.52 and automake
version >= 1.6.  No other non-standard libraries should be required.


Getting started
---------------

To get a usable configure system after checking source out of CVS, run

./bootstrap

This will process all the automake/autoconf files and build a configure
script.


Development Objectives and Principles
-------------------------------------

The objectives for the development of netcat6 are:
  * To produce a functional replacement of netcat with complete AF
     independence (especially support for IPv6).
  * To provide the functions of netcat that are useful without the features
     that are unnecessary or where a better method exists.
  * To provide additional functionality that would be useful in this type
     of application.
  * Clear and well structured code and documentation.  netcat6 should serve as
     an excellent example of AF independant network programming.
  * To be highly portable (to many platforms and operating systems) as long
     as the code can remain clear and well structred.

The following are NOT objectives for netcat6 development:
  * Complete compatability with the original netcat.

The following are the principles for netcat6:
  * Open design: The design should not be secret (nc6 is GPL, so both design
     and implementation are public).
  * Economy of mechanism: Keep the design as simple as possible.
  * Least astonishment: The application behavior should match what is
     naively expected.
  * Simplicity of function: The application should perform functions that are
     useful in the context of general use of the application (eg. it should 
     not become bloated with oft unnecessary features).


Style guide
-----------

Read Linus Torvalds' CodingStyle document (included in the linux kernel
sources, in the Documentation directory). It is really an enlightening 
reading. Since the beginning of its development, the nc6 code has 
been written according to the rules described by this document. 

The most important coding style rules for nc6 are:

* 8-column indent.

* Always open curly bracket on same line as keyword. e.g.:

  /* this is the preferred layout */
  for (i = 0; i < len; ++i) {
          ...
  }

  If this is not possible (but there must be a __REALLY__ valid reason) 
  put it on the following line, vertically aligned with the keyword. e.g.:

  /* this is also acceptable, but deprecated */
  for (i = 0; i < len; ++i) 
  {
          ...
  }

  A valid reason is if the line after the keyword must be split. e.g.:
  
  if (some_really_really_long_set_of_checks_and_operations_that_will = 0 &&
      eventually_take_up_more_than_one_line != NULL)
  {
  	...
  }

* No space before the semicolon.

* Space around most operators.

* Space around a "complex" subscript (e.g. inside brackets).

* Blank lines between chunks that do different things.

* Cuddled elses.

* No space between function name and its opening parenthesis.

* Space after each comma.

* Long lines broken after an operator.

* Line up corresponding items (especially function arguments and, if possible,
  operations on related variables) vertically. e.g.:
 
  /* do this for both invocations ... */
  foo(arg1,
      arg2);
      
  /* ... and declarations */
  int foo(int arg1,
          long arg2);

  /* do this only if variables arg1, arg2a and longname are related */
  arg1     = 1;
  arg2a    = 2;
  longname = 3;
  
* Don't assume that NULL is equal to zero. On some platforms this may not
  be true. Use: 
  
  	assert(ptr != NULL);
	
  instead of:

  	assert(ptr);

* In a similar way, don't assume that TRUE is one and FALSE is zero. These
  are the values assigned respectively to the constants TRUE and FALSE at 
  the moment, but those values can changed in future releases of nc6. Use: 
  
  	assert(flag1 == TRUE);
  	assert(flag2 == FALSE);
	
  instead of:

  	assert(flag1);
  	assert(!flag2);
	
* Omit redundant punctuation as long as clarity doesn't suffer.

* The pointer operators * and & must go __before__ a variable of function 
  name and not after the pointer type. Also, in casts there must be a space
  between the pointer type and the * or & operator.
  For instance, don't write:

	/* do __NOT__ do this!!! */
	int* foo(const char* str)
	{
		int* ret;
		
		ret = (int*)xmalloc(safe_atoi(str));
		
		return ret;
	}

  but:

	/* this is the correct layout for the code above */
	int *foo(const char *str)
	{
		int *ret;
		
		ret = (int *)xmalloc(safe_atoi(str));
		
		return ret;
	}
  
* Avoid declaring global variables, especially external (non-static) ones.
  There is rarely a need for this and it can indicate a badly thought out
  design.

* Try not to #define preprocessor constants when possible (usually this is
  when the constant is only used in a single module and will be inlined by the
  compiler).  The definition:

  static const int SOME_NUMBER = 0x02;

  is much better than:

  #define SOME_NUMBER 0x02



Version numbering
-----------------

nc6 will use a simple major.minor version numbering scheme.  For each minor
release the minor number is incremented, and for a major release the major
number is incremented and the minor number reset to 0.

A typical release pattern might be as follows:

	0.8
	0.9
	0.10
	0.11
	1.0
	1.1
	1.2
	2.0
	etc

Versions built from the CVS tree will have the version number of the last
release, appended with the '-cvs' modifier (eg. 1.2-cvs).  This indicates
the source is based on the 1.2 release, but may contain modifications.

Each release should also contain a corresponding CVS tag in the repository -
of the form 'release_XX_XX' (eg. release_0_11).


Making a Release 
----------------

To make a new release, the following process should be followed:

1) Ensure the nc6.pot and associated .po files are up to date with the source
2) Clean the source tree (make maintainer-clean)
3) Edit the ChangeLog
4) Edit the version number in configure.ac (and be sure to remove the '-cvs')
5) Commit changes
6) Tag the repository with the release tag
7) ./bootstrap
8) ./configure
9) make dist
10) make distcheck

This will build a tar.gz and tar.bz2 in the root of the source tree.  These
should be made available for download from the deepspace6 website.

11) Clean the source tree again (make maintainer-clean)
12) Edit configure.ac to add '-cvs' onto the end of the version number
13) Commit changes



Release Announcements
---------------------

(TODO: where should releases be announced to?)