Added some additional guidelines and clarified some existing points.

diff --git a/doc/devel/guidelines b/doc/devel/guidelines
index 0c20dd2319b2f88861e20abe5471a36039c6d117..82433d2166f6ea4a4adf09042fc8fce9cf4391fe 100644 (file)
--- a/doc/devel/guidelines
+++ b/doc/devel/guidelines
@@ -8,8 +8,19 @@ Please add to this file when new points come up.
 C source
 --------
 
-We require ISO C support, or at least prototypes, to *build* OpenLDAP,
-but .h files that will be installed should support K&R C.
+OpenLDAP requires many Standard C features to *build*.  This
+includes functional prototypes and offsetof macro.  It is
+possible to *build* OpenLDAP with a number of C translators
+which are not fully compliant with Standard C.
+
+OpenLDAP supports compiling and linking *with* applications
+with most C compilers and libraries.   The installed headers
+are designed to provide K&R C compatiable function declarations
+on non-standard compilers.  In cases where the compiler does
+not define __STDC__ but requires prototypes (ie: MSVC), the
+application should define LDAP_NEEDS_PROTOTYPES.  In cases
+where the compiler does define __STDC__ but does not support
+prototypes, the application should define LDAP_NO_PROTOTYPES.
 
 .c files in the OpenLDAP source tree MUST #include "portable.h" before
 any other include file, even system includes.  portable.h may control
@@ -21,8 +32,11 @@ it is not installed.  They can use ldap_features.h, though.)
 .h files that *are* installed (from include/) should not depend on it.
 
 Avoid unnecessary changes, like reindenting code, even if that leaves
-the code a little more ugly.  Unnecessary changes make it harder to
-maintain and merge different CVS branches of the source.
+the code a little ugly.  Often switching your editors tab stops to
+4 or 8 may make code easier to read.  Unnecessary changes make it
+harder to maintain and merge different CVS branches of the source.
+
+Please follow the style of surrounding code.
 
 Use feature-specific #if tests (like #ifdef HAVE_LWP) which configure
 can figure out, not system-specific test (like #ifdef __SunOS_5_6).
@@ -35,11 +49,17 @@ designed to be equivalent to standard C's <xxx.h> file.
 
 Nonstatic function and variable definitions in .c files should be
 preceded by their declarations in .h files.  Avoid implicit function
-declarations.  Avoid external declarations in .c files.
+declarations.  External declarations with should be avoided.  In
+.c files, include the appropriate .h file to obtain the declaration.
+If the declaration is not available in any system header, add it
+to the most appropriate ac/xxx.h header.  Do NOT add extern
+declarations to .c files.
 
 When a function returns non-void, it should return a meaningful value.
 Avoid implicit int.
 
+It is recommended that ldap_cdef.h macros LDAP_F and LDAP_P be used
+even for non-installed headers.  See lber.h and ldap.h for examples.
 
 
 CVS updating
@@ -47,12 +67,13 @@ CVS updating
 
 <URL:http://www.openldap.org/repo.html> describes how to check out
 -stable.  To get the -devel (HEAD) branch, omit `-r OPENLDAP_STABLE'.
+You can use 'cvs status -v README' to get a list available CVS tags.
 
-Core members should subscribe to the private -core mailinglist and
+Core members should subscribe to the private -core mailing list and
 coordinate activities there.
 
-Do not commit a patch, however small, without at least testing that it
-compiles.
+Please test patches before committing.  This should include compiling
+and linking the system AND running the test suite.
 
 In general, a patch/bugfix should be applied to -devel and tested.
 When the patch is considered stable, then it can be merged into -stable.