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.
diff --git a/HACKING b/HACKING
index 6f3e03b..8497280 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 @@
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 @@
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.