2005-04-07 Paul Jakma <paul.jakma@sun.com>

	* (global): Fix up list loops to match changes in lib/linklist,
	  and some basic auditing of usage.
	* configure.ac: define QUAGGA_NO_DEPRECATED_INTERFACES
	* HACKING: Add notes about deprecating interfaces and commands.
	* lib/linklist.h: Add usage comments.
	  Rename getdata macro to listgetdata.
	  Rename nextnode to listnextnode and fix its odd behaviour to be
	  less dangerous.
	  Make listgetdata macro assert node is not null, NULL list entries
          should be bug condition.
          ALL_LIST_ELEMENTS, new macro, forward-referencing macro for use
          with for loop, Suggested by Jim Carlson of Sun.
          Add ALL_LIST_ELEMENTS_RO for cases which obviously do not need the
          "safety" of previous macro.
	  LISTNODE_ADD and DELETE macros renamed to ATTACH, DETACH, to
	  distinguish from the similarly named functions, and reflect their
	  effect better.
	  Add a QUAGGA_NO_DEPRECATED_INTERFACES define guarded section
	  with the old defines which were modified above,
	  for backwards compatibility - guarded to prevent Quagga using it..
	* lib/linklist.c: fix up for linklist.h changes.
	* ospf6d/ospf6_abr.c: (ospf6_abr_examin_brouter) change to a single
	  scan of the area list, rather than scanning all areas first for
	  INTER_ROUTER and then again for INTER_NETWORK. According to
	  16.2, the scan should be area specific anyway, and further
	  ospf6d does not seem to implement 16.3 anyway.

1 files changed, 30 insertions, 1 deletions

diff --git a/HACKING b/HACKING
index 6f3e03b2..84972807 100644
--- a/HACKING
+++ b/HACKING
@@ -1,5 +1,5 @@
 -*- mode: text; -*-
-$Id: HACKING,v 1.18 2005/04/05 10:14:50 paul Exp $
+$Id: HACKING,v 1.19 2005/04/07 07:30:20 paul Exp $
 
 GUIDELINES FOR HACKING ON QUAGGA
 
@@ -44,6 +44,32 @@ these header files:
   lib/log.h	logging levels and usage guidance
   [more to be added]
 
+If changing an exported interface, please try to deprecate the interface in
+an orderly manner. If at all possible, try to retain the old deprecated
+interface as is, or functionally equivalent. Make a note of when the
+interface was deprecated and guard the deprecated interface definitions in
+the header file, ie:
+
+/* Deprecated: 20050406 */
+#if !defined(QUAGGA_NO_DEPRECATED_INTERFACES)
+#warning "Using deprecated <libname> (interface(s)|function(s))"
+...
+#endif /* QUAGGA_NO_DEPRECATED_INTERFACES */
+
+To ensure that the core Quagga sources do not use the deprecated interfaces
+(you should update Quagga sources to use new interfaces, if applicable)
+while allowing external sources to continue to build. Deprecated interfaces
+should be excised in the next unstable cycle.
+
+If changing or removing a command definition, *ensure* that you properly
+deprecate it - use the _DEPRECATED form of the appropriate DEFUN macro. This
+is *critical*. Even if the command can no longer function, you *must* still
+implement it as a do-nothing stub. Failure to follow this causes grief for
+systems administrators. Deprecated commands should be excised in the next
+unstable cycle. A list of deprecated commands should be collated for each
+release.
+
+See also below regarding SHARED LIBRARY VERSIONING.
 
 CHANGELOG
 
@@ -79,6 +105,9 @@ If any errors occur, move tags as needed and start over from the fresh
 checkouts.  Do not append to tarballs, as this has produced
 non-standards-conforming tarballs in the past.
 
+[TODO: collation of a list of deprecated commands. Possibly can be scripted
+to extract from vtysh/vtysh_cmd.c]
+
 TOOL VERSIONS
 
 Require versions of support tools are listed in INSTALL.quagga.txt.