diff options
Diffstat (limited to 'HACKING')
| -rw-r--r-- | HACKING | 46 |
1 files changed, 32 insertions, 14 deletions
@@ -17,6 +17,7 @@ Contents: * STABLE PLATFORMS AND DAEMONS * IMPORT OR UPDATE VENDOR SPECIFIC ROUTING PROTOCOLS + GUIDELINES FOR HACKING ON QUAGGA [this is a draft in progress] @@ -98,6 +99,7 @@ release. See also below regarding SHARED LIBRARY VERSIONING. + COMPILE-TIME CONDITIONAL CODE Please think very carefully before making code conditional at compile time, @@ -121,12 +123,13 @@ rather than: Note that the former approach requires ensuring that SOME_SYMBOL will be defined (watch your AC_DEFINEs). + COMMIT MESSAGES The commit message should provide: -* A suitable one-line summary as the very first line of the message, in the - form: +* A suitable one-line summary followed by a blank line as the very + first line of the message, in the form: topic: high-level, one line summary @@ -141,12 +144,14 @@ The commit message should provide: to provide a short description of the general intent of the patch, in terms of the problem it solves and how it achieves it, to help reviewers -understand. +understand. +The one-line summary must be limited to 54 characters, and all other +lines to 72 characters. The reason for such itemised commit messages is to encourage the author to self-review every line of the patch, as well as provide reviewers an index -of which changes are intended, along with a short description for each. +of which changes are intended, along with a short description for each. Some discretion is obviously required. A C-to-english description is not desireable. For short patches, a per-function/file break-down may be redundant. For longer patches, such a break-down may be essential. @@ -157,11 +162,13 @@ given the one-line summary): zebra: Enhance frob FSM to detect loss of frob * (general) Add a new DOWN state to the frob state machine - to allow the barinator to detect loss of frob. + to allow the barinator to detect loss of frob. * frob.h: (struct frob) Add DOWN state flag. * frob.c: (frob_change) set/clear DOWN appropriately on state change. * bar.c: (barinate) Check frob for DOWN state. +Note that the commit message format follows git norms, so that "git +log --oneline" will have useful output. HACKING THE BUILD SYSTEM @@ -170,13 +177,14 @@ etc.), try to check that the following things still work: - make dist - resulting dist tarball builds - - out-of-tree builds + - out-of-tree builds The quagga.net site relies on make dist to work to generate snapshots. It must work. Common 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 apppropriate commit with a release tag (follow existing @@ -199,7 +207,7 @@ RELEASE PROCEDURE The tarball which 'make dist' creates is the tarball to be released! The git-archive step ensures you're working with code corresponding to that in the official repository, and also carries out keyword expansion. If any -errors occur, move tags as needed and start over from the fresh checkouts. +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. @@ -239,23 +247,33 @@ library libzebra and the included daemons should always be built and installed together. +GIT COMMIT SUBSMISSION + +The preferred method for changes is to provide git commits via a +publically-accessible git repository. + +All content guidelines in PATCH SUBMISSION apply. + + PATCH SUBMISSION * Send a clean diff against the 'master' branch of the quagga.git - repository, in unified diff format, preferably with the '-p' argument to + repository, in unified diff format, preferably with the '-p' argument to show C function affected by any chunk, and with the -w and -b arguments to - minimise changes. E.g: + minimise changes. E.g: git diff -up mybranch..remotes/quagga.net/master - Or by using git-format-patch. + It is preferable to use git format-patch, and even more preferred to + publish a git repostory. -* Not doing so is a definite hindrance to patch application. + If not using git format-patch, Include the commit message in the email. -* Include NEWS entries as appropriate. +* After a commit, code should have comments explaining to the reviewer + why it is correct, without reference to history. The commit message + should explain why the change is correct. -* Please, please include an appropriate commit message with any emailed - patches. Doing so makes it easier to review a patch, and apply it. +* Include NEWS entries as appropriate. * Include only one semantic change or group of changes per patch. |