summaryrefslogtreecommitdiff
path: root/HACKING
diff options
context:
space:
mode:
authorPaul Jakma <paul@quagga.net>2009-07-28 16:04:35 +0100
committerPaul Jakma <paul@quagga.net>2009-07-30 15:51:45 +0100
commit3de4277ba9b25ff03710d7c004bf708accffd5c7 (patch)
treedf5d9125635c6101cf6e1224f5b8b1af25fe91e4 /HACKING
parent05cf46badbad99b76c4e974c7306c14494d1000e (diff)
[doc] Update HACKING
* HACKING: Update to reflect git stripping []'s, and to allow for more discretion to avoid redundancy in commit messages.
Diffstat (limited to 'HACKING')
-rw-r--r--HACKING38
1 files changed, 24 insertions, 14 deletions
diff --git a/HACKING b/HACKING
index d0fd4b3c..5a207274 100644
--- a/HACKING
+++ b/HACKING
@@ -128,31 +128,39 @@ The commit message should provide:
* A suitable one-line summary as the very first line of the message, in the
form:
- [topic] high-level, one line summary
+ topic: high-level, one line summary
- Where topic may be name of a subdirectory, and/or daemon.
+ Where topic would tend to be name of a subdirectory, and/or daemon, unless
+ there's a more suitable topic (e.g. 'build'). This topic is used to
+ organise change summaries in release announcements.
* An optional introduction, discussing the general intent of the change.
-* a short description of each change made, preferably:
+* A short description of each change made, preferably:
* file by file
* function by function (use of "ditto", or globs is allowed)
-to provide a short description of the general intent of the patch.
+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.
+
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.
+
An example (where the general discussion is obviously somewhat redundant,
given the one-line summary):
-[zebra] Enhance frob FSM to detect loss of frob
+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.
- * 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.
+* (general) Add a new DOWN state to the frob state machine
+ 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.
HACKING THE BUILD SYSTEM
@@ -183,7 +191,7 @@ RELEASE PROCEDURE
--prefix=quagga-release/ master | tar -xf -
cd quagga-release
- ./update-autotools
+ autoreconf -i
./configure
make
make dist
@@ -195,6 +203,8 @@ 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.
+See also: http://wiki.quagga.net/index.php/Main/Processes
+
[TODO: collation of a list of deprecated commands. Possibly can be scripted
to extract from vtysh/vtysh_cmd.c]
@@ -236,7 +246,7 @@ PATCH SUBMISSION
show C function affected by any chunk, and with the -w and -b arguments to
minimise changes. E.g:
- git diff -u -p -w -b mybranch..remotes/quagga.net/master
+ git diff -up mybranch..remotes/quagga.net/master
Or by using git-format-patch.