-*- mode: text; -*-
-
-$Id: HACKING,v 1.7 2004/07/23 16:23:56 gdt Exp $
+$Id: HACKING,v 1.20 2005/04/25 00:37:03 paul Exp $
GUIDELINES FOR HACKING ON QUAGGA
[this is a draft in progress]
-Generally, GNU coding standards apply. The indentation style is a bit
-different from standard GNU style, and the existing style should be
-maintained and used for new code.
+GNU coding standards apply. Indentation follows the result of
+invoking GNU indent (as of 2.2.8a) with no arguments. Note that this
+uses tabs instead of spaces where possible for leading whitespace, and
+assumes that tabs are every 8 columns. Do not attempt to redefine the
+location of tab stops. Note also that some indentation does not
+follow GNU style. This is a historical accident, and we generally
+only clean up whitespace when code is unmaintainable due to whitespace
+issues, as fewer changes from zebra lead to easier merges.
+
+For GNU emacs, use indentation style "gnu".
+
+For Vim, use the following lines (note that tabs are at 8, and that
+softtabstop sets the indentation level):
+
+set tabstop=8
+set softtabstop=2
+set shiftwidth=2
+set noexpandtab
Be particularly careful not to break platforms/protocols that you
cannot test.
should in many cases upgrade the comments when necessary for a
reviewer to conclude that the change has no unintended consequences.
+Each file in CVS should have the RCS keyword Id, somewhere very near
+the top, commented out appropriately for the file type. Just add
+<dollar>Id:<dollar>, replacing <dollar> with $. See line 2 of HACKING
+for an example; on checkout :$ is expanded to include the value.
+
+Please document fully the proper use of a new function in the header file
+in which it is declared. And please consult existing headers for
+documentation on how to use existing functions. In particular, please consult
+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.
+
+Note: If you wish, you can test for GCC and use a function
+marked with the 'deprecated' attribute. However, you must provide the
+#warning for other compilers.
+
+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
Add a ChangeLog entry whenever changing code, except for minor fixes
to a commit (with a ChangeLog entry) within the last few days.
-There is at present a mixed style for ChangeLog, with some changes
-being described in per-directory ChangeLog files, and some at top
-level.
+Most directories have a ChangeLog file; changes to code in that
+directory should go in the per-directory ChangeLog. Global or
+structural changes should also be mentioned in the top-level
+ChangeLog.
+
+Certain directories do not contain project code, but contain project
+meta-data, eg packaging information, changes to files in these directory may
+not require the global ChangeLog to be updated (at the discretion of the
+maintainer who usually maintains that meta-data). Also, CVS meta-data such
+as cvsignore files do not require ChangeLog updates, just a sane commit
+message.
+
+
+HACKING THE BUILD SYSTEM
+
+If you change or add to the build system (configure.ac, any Makefile.am,
+etc.), try to check that the following things still work:
+
+ - make dist
+ - resulting dist tarball builds
+ - out-of-tree builds
+
+The quagga.net site relies on make dist to work to generate snapshots. It
+must work. Commong problems are to forget to have some additional file
+included in the dist, or to have a make rule refer to a source file without
+using the srcdir variable.
+
+RELEASE PROCEDURE
+
+ Tag the repository with release tag (follow existing conventions).
+ [This enables recreating the release, and is just good CM practice.]
+
+ Check out the tag, and do a test build.
+
+ In an empty directory, do a fresh checkout with -r <release-tag>
+ [This makes the dates in the tarball be the modified dates in CVS.]
+
+ ./configure
+ make dist
+
+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.
+Required versions should only be done with due deliberation, as it can
+cause environments to no longer be able to compile quagga.
-[TBD: resolve per-dir vs top-level, perhaps by reading GNU coding
-standards]
SHARED LIBRARY VERSIONING
library libzebra and the included daemons should always be built and
installed together.
+
PATCH SUBMISSION
* Send a clean diff against the head of CVS in unified diff format, eg by:
- cvs <cvs opts> diff -uwb ....
+ cvs <cvs opts> diff -upwb ....
* Include ChangeLog and NEWS entries as appropriate before the patch
- (or in it if you are 100% up to date).
+ (or in it if you are 100% up to date). A good ChangeLog makes it easier to
+ review a patch, hence failure to include a good ChangeLog is prejudicial
+ to proper review of the patch, and hence the possibility of inclusion.
-* Inclue only one semantic change or group of changes per patch.p
+* Include only one semantic change or group of changes per patch.
* Do not make gratuitous changes to whitespace. See the w and b arguments
to diff.
willing to verify -current occasionally, that platform may be
dropped from the "should be checked" list.
+
PATCH APPLICATION TO CVS
* Only apply patches that meet the submission guidelines.
mailinglist.
* Give an appropriate commit message, eg the ChangeLog entry should suffice,
- if it does not, then the ChangeLog entry itself needs to be corrected.
+ if it does not, then the ChangeLog entry itself needs to be corrected. The
+ commit message text should be identical to that added to the ChangeLog
+ message. (One suggestion: when commiting, use your editor to read in the
+ ChangeLog and delete all previous ChangeLogs.)
* By committing a patch, you are responsible for fixing problems
resulting from it (or backing it out).
+
STABLE PLATFORMS AND DAEMONS
The list of platforms that should be tested follow. This is a list
BSD (Free, Net or Open, any platform) # without capabilities
GNU/Linux (any distribution, i386)
- [future: some 64-bit machine, e.g. NetBSD/sparc64]
- [Solaris? (could address 64-bit issue)]
+ Solaris (strict alignment, any platform)
+ [future: NetBSD/sparc64]
The list of daemons that are thought to be stable and that should be
tested are:
ospfd
ripngd
+Daemons which are in a testing phase are
+
+ ospf6d
+ isisd
+ watchquagga
+
+
IMPORT OR UPDATE VENDOR SPECIFIC ROUTING PROTOCOLS
The source code of Quagga is based on two vendors:
zebra_org (http://www.zebra.org/)
isisd_sf (http://isisd.sf.net/)
+[20041105: Is isisd.sf.netf still where isisd word is happening, or is
+the quagga repo now the canonical place? The last tarball on sf is
+two years old. --gdt]
+
In order to import source code, the following procedure should be used:
* Tag the Current Quagga CVS repository:
projects / mirror_frr.git / blobdiff