]>
Commit | Line | Data |
---|---|---|
d9fd04c2 | 1 | -*- mode: text; -*- |
2 | ||
863076db | 3 | $Id: HACKING,v 1.8 2004/09/01 20:13:23 hasso Exp $ |
d9fd04c2 | 4 | |
5 | GUIDELINES FOR HACKING ON QUAGGA | |
6 | ||
d9fd04c2 | 7 | [this is a draft in progress] |
8 | ||
863076db | 9 | GNU coding standards apply. Indentation follows the result of |
10 | invoking GNU indent (as of 2.2.8a) with no arguments. Note that this | |
11 | uses tabs instead of spaces where possible for leading whitespace, and | |
12 | assumes that tabs are every 8 columns. Do not attempt to redefine the | |
13 | location of tab stops. Note also that some indentation does not | |
14 | follow GNU style. This is a historical accident, and we generally | |
15 | only clean up whitespace when code is unmaintainable due to whitespace | |
16 | issues, as fewer changes from zebra lead to easier merges. | |
17 | ||
18 | For GNU emacs, use indentation style "gnu". | |
19 | ||
20 | For Vim, use the following lines (note that tabs are at 8, and that | |
21 | softtabstop sets the indentation level): | |
22 | ||
23 | set tabstop=8 | |
24 | set softtabstop=2 | |
25 | set shiftwidth=2 | |
26 | set noexpandtab | |
d9fd04c2 | 27 | |
2934f28e | 28 | Be particularly careful not to break platforms/protocols that you |
29 | cannot test. | |
30 | ||
31 | New code should have good comments, and changes to existing code | |
32 | should in many cases upgrade the comments when necessary for a | |
33 | reviewer to conclude that the change has no unintended consequences. | |
34 | ||
35 | CHANGELOG | |
36 | ||
37 | Add a ChangeLog entry whenever changing code, except for minor fixes | |
38 | to a commit (with a ChangeLog entry) within the last few days. | |
39 | ||
40 | There is at present a mixed style for ChangeLog, with some changes | |
41 | being described in per-directory ChangeLog files, and some at top | |
42 | level. | |
43 | ||
44 | [TBD: resolve per-dir vs top-level, perhaps by reading GNU coding | |
45 | standards] | |
46 | ||
b7a97f82 | 47 | SHARED LIBRARY VERSIONING |
48 | ||
49 | [this section is at the moment just gdt's opinion] | |
50 | ||
51 | Quagga builds several shared libaries (lib/libzebra, ospfd/libospf, | |
52 | ospfclient/libsopfapiclient). These may be used by external programs, | |
53 | e.g. a new routing protocol that works with the zebra daemon, or | |
54 | ospfapi clients. The libtool info pages (node Versioning) explain | |
55 | when major and minor version numbers should be changed. These values | |
56 | are set in Makefile.am near the definition of the library. If you | |
57 | make a change that requires changing the shared library version, | |
58 | please update Makefile.am. | |
59 | ||
60 | libospf exports far more than it should, and is needed by ospfapi | |
61 | clients. Only bump libospf for changes to functions for which it is | |
62 | reasonable for a user of ospfapi to call, and please err on the side | |
63 | of not bumping. | |
64 | ||
65 | There is no support intended for installing part of zebra. The core | |
66 | library libzebra and the included daemons should always be built and | |
67 | installed together. | |
68 | ||
d9fd04c2 | 69 | PATCH SUBMISSION |
70 | ||
85cf0a0d | 71 | * Send a clean diff against the head of CVS in unified diff format, eg by: |
72 | cvs <cvs opts> diff -uwb .... | |
d9fd04c2 | 73 | |
74 | * Include ChangeLog and NEWS entries as appropriate before the patch | |
75 | (or in it if you are 100% up to date). | |
76 | ||
77 | * Inclue only one semantic change or group of changes per patch.p | |
78 | ||
85cf0a0d | 79 | * Do not make gratuitous changes to whitespace. See the w and b arguments |
80 | to diff. | |
d9fd04c2 | 81 | |
82 | * State on which platforms and with what daemons the patch has been | |
83 | tested. Understand that if the set of testing locations is small, | |
84 | and the patch might have unforeseen or hard to fix consequences that | |
85 | there may be a call for testers on quagga-dev, and that the patch | |
86 | may be blocked until test results appear. | |
87 | ||
88 | If there are no users for a platform on quagga-dev who are able and | |
89 | willing to verify -current occasionally, that platform may be | |
90 | dropped from the "should be checked" list. | |
91 | ||
92 | PATCH APPLICATION TO CVS | |
93 | ||
94 | * Only apply patches that meet the submission guidelines. | |
95 | ||
96 | * If a patch is large (perhaps more than 100 new/changed lines), tag | |
97 | the repository before and after the change with e.g. before-foo-fix | |
98 | and after-foo-fix. | |
99 | ||
100 | * If the patch might break something, issue a call for testing on the | |
101 | mailinglist. | |
102 | ||
4134ceb7 | 103 | * Give an appropriate commit message, eg the ChangeLog entry should suffice, |
104 | if it does not, then the ChangeLog entry itself needs to be corrected. | |
105 | ||
d9fd04c2 | 106 | * By committing a patch, you are responsible for fixing problems |
107 | resulting from it (or backing it out). | |
108 | ||
109 | STABLE PLATFORMS AND DAEMONS | |
110 | ||
111 | The list of platforms that should be tested follow. This is a list | |
112 | derived from what quagga is thought to run on and for which | |
113 | maintainers can test or there are people on quagga-dev who are able | |
114 | and willing to verify that -current does or does not work correctly. | |
115 | ||
116 | BSD (Free, Net or Open, any platform) # without capabilities | |
117 | GNU/Linux (any distribution, i386) | |
118 | [future: some 64-bit machine, e.g. NetBSD/sparc64] | |
119 | [Solaris? (could address 64-bit issue)] | |
120 | ||
121 | The list of daemons that are thought to be stable and that should be | |
122 | tested are: | |
123 | ||
124 | zebra | |
125 | bgpd | |
126 | ripd | |
127 | ospfd | |
128 | ripngd | |
1f431d2d | 129 | |
9e867fe6 | 130 | IMPORT OR UPDATE VENDOR SPECIFIC ROUTING PROTOCOLS |
131 | ||
132 | The source code of Quagga is based on two vendors: | |
133 | ||
134 | zebra_org (http://www.zebra.org/) | |
135 | isisd_sf (http://isisd.sf.net/) | |
136 | ||
137 | In order to import source code, the following procedure should be used: | |
138 | ||
139 | * Tag the Current Quagga CVS repository: | |
140 | ||
141 | cvs tag import_isisd_sf_20031223 | |
142 | ||
143 | * Import the source code into the Quagga's framework. You must not modified | |
144 | this source code. It will be merged later. | |
145 | ||
146 | cd dir_isisd | |
147 | export CVSROOT=:pserver:LOGIN@anoncvs.quagga.net:/var/cvsroot | |
148 | cvs import quagga/isisd isisd_sf isisd_sf_20031223 | |
149 | ---COMMENTS--- | |
150 | Vendor: [isisd_sf] Sampo's ISISd from Sourceforge | |
151 | Tag: [isisd_sf_20031217] Current CVS release | |
152 | --- | |
153 | ||
154 | * Update your Quagga's directory: | |
155 | ||
156 | cd dir_quagga | |
157 | cvs update -dP | |
158 | ||
159 | or | |
160 | ||
161 | cvs co -d quagga_isisd quagga | |
162 | ||
163 | * Merge the code, then commit: | |
164 | ||
165 | cvs commit | |
166 |