]>
Commit | Line | Data |
---|---|---|
d9fd04c2 | 1 | -*- mode: text; -*- |
74a2dd7b | 2 | $Id: HACKING,v 1.20 2005/04/25 00:37:03 paul Exp $ |
d9fd04c2 | 3 | |
4 | GUIDELINES FOR HACKING ON QUAGGA | |
5 | ||
d9fd04c2 | 6 | [this is a draft in progress] |
7 | ||
863076db | 8 | GNU coding standards apply. Indentation follows the result of |
9 | invoking GNU indent (as of 2.2.8a) with no arguments. Note that this | |
10 | uses tabs instead of spaces where possible for leading whitespace, and | |
11 | assumes that tabs are every 8 columns. Do not attempt to redefine the | |
12 | location of tab stops. Note also that some indentation does not | |
13 | follow GNU style. This is a historical accident, and we generally | |
14 | only clean up whitespace when code is unmaintainable due to whitespace | |
15 | issues, as fewer changes from zebra lead to easier merges. | |
16 | ||
17 | For GNU emacs, use indentation style "gnu". | |
18 | ||
19 | For Vim, use the following lines (note that tabs are at 8, and that | |
20 | softtabstop sets the indentation level): | |
21 | ||
22 | set tabstop=8 | |
23 | set softtabstop=2 | |
24 | set shiftwidth=2 | |
25 | set noexpandtab | |
d9fd04c2 | 26 | |
2934f28e | 27 | Be particularly careful not to break platforms/protocols that you |
28 | cannot test. | |
29 | ||
30 | New code should have good comments, and changes to existing code | |
31 | should in many cases upgrade the comments when necessary for a | |
32 | reviewer to conclude that the change has no unintended consequences. | |
33 | ||
697877eb | 34 | Each file in CVS should have the RCS keyword Id, somewhere very near |
35 | the top, commented out appropriately for the file type. Just add | |
36 | <dollar>Id:<dollar>, replacing <dollar> with $. See line 2 of HACKING | |
37 | for an example; on checkout :$ is expanded to include the value. | |
38 | ||
5e764774 | 39 | Please document fully the proper use of a new function in the header file |
40 | in which it is declared. And please consult existing headers for | |
41 | documentation on how to use existing functions. In particular, please consult | |
42 | these header files: | |
43 | ||
44 | lib/log.h logging levels and usage guidance | |
45 | [more to be added] | |
46 | ||
1eb8ef25 | 47 | If changing an exported interface, please try to deprecate the interface in |
48 | an orderly manner. If at all possible, try to retain the old deprecated | |
49 | interface as is, or functionally equivalent. Make a note of when the | |
50 | interface was deprecated and guard the deprecated interface definitions in | |
51 | the header file, ie: | |
52 | ||
53 | /* Deprecated: 20050406 */ | |
54 | #if !defined(QUAGGA_NO_DEPRECATED_INTERFACES) | |
55 | #warning "Using deprecated <libname> (interface(s)|function(s))" | |
56 | ... | |
57 | #endif /* QUAGGA_NO_DEPRECATED_INTERFACES */ | |
58 | ||
59 | To ensure that the core Quagga sources do not use the deprecated interfaces | |
60 | (you should update Quagga sources to use new interfaces, if applicable) | |
61 | while allowing external sources to continue to build. Deprecated interfaces | |
62 | should be excised in the next unstable cycle. | |
63 | ||
74a2dd7b | 64 | Note: If you wish, you can test for GCC and use a function |
65 | marked with the 'deprecated' attribute. However, you must provide the | |
66 | #warning for other compilers. | |
67 | ||
1eb8ef25 | 68 | If changing or removing a command definition, *ensure* that you properly |
69 | deprecate it - use the _DEPRECATED form of the appropriate DEFUN macro. This | |
70 | is *critical*. Even if the command can no longer function, you *must* still | |
71 | implement it as a do-nothing stub. Failure to follow this causes grief for | |
72 | systems administrators. Deprecated commands should be excised in the next | |
73 | unstable cycle. A list of deprecated commands should be collated for each | |
74 | release. | |
75 | ||
76 | See also below regarding SHARED LIBRARY VERSIONING. | |
5e764774 | 77 | |
74a2dd7b | 78 | |
2934f28e | 79 | CHANGELOG |
80 | ||
81 | Add a ChangeLog entry whenever changing code, except for minor fixes | |
82 | to a commit (with a ChangeLog entry) within the last few days. | |
83 | ||
18323bb2 | 84 | Most directories have a ChangeLog file; changes to code in that |
85 | directory should go in the per-directory ChangeLog. Global or | |
86 | structural changes should also be mentioned in the top-level | |
87 | ChangeLog. | |
2934f28e | 88 | |
1f8f61a7 | 89 | Certain directories do not contain project code, but contain project |
90 | meta-data, eg packaging information, changes to files in these directory may | |
91 | not require the global ChangeLog to be updated (at the discretion of the | |
92 | maintainer who usually maintains that meta-data). Also, CVS meta-data such | |
93 | as cvsignore files do not require ChangeLog updates, just a sane commit | |
94 | message. | |
95 | ||
74a2dd7b | 96 | |
97 | HACKING THE BUILD SYSTEM | |
98 | ||
99 | If you change or add to the build system (configure.ac, any Makefile.am, | |
100 | etc.), try to check that the following things still work: | |
101 | ||
102 | - make dist | |
103 | - resulting dist tarball builds | |
104 | - out-of-tree builds | |
105 | ||
106 | The quagga.net site relies on make dist to work to generate snapshots. It | |
107 | must work. Commong problems are to forget to have some additional file | |
108 | included in the dist, or to have a make rule refer to a source file without | |
109 | using the srcdir variable. | |
110 | ||
0d7e9134 | 111 | RELEASE PROCEDURE |
112 | ||
113 | Tag the repository with release tag (follow existing conventions). | |
114 | [This enables recreating the release, and is just good CM practice.] | |
115 | ||
116 | Check out the tag, and do a test build. | |
117 | ||
118 | In an empty directory, do a fresh checkout with -r <release-tag> | |
119 | [This makes the dates in the tarball be the modified dates in CVS.] | |
120 | ||
0d7e9134 | 121 | ./configure |
122 | make dist | |
123 | ||
124 | If any errors occur, move tags as needed and start over from the fresh | |
125 | checkouts. Do not append to tarballs, as this has produced | |
126 | non-standards-conforming tarballs in the past. | |
127 | ||
1eb8ef25 | 128 | [TODO: collation of a list of deprecated commands. Possibly can be scripted |
129 | to extract from vtysh/vtysh_cmd.c] | |
130 | ||
74a2dd7b | 131 | |
fbb67099 | 132 | TOOL VERSIONS |
133 | ||
134 | Require versions of support tools are listed in INSTALL.quagga.txt. | |
135 | Required versions should only be done with due deliberation, as it can | |
136 | cause environments to no longer be able to compile quagga. | |
137 | ||
74a2dd7b | 138 | |
b7a97f82 | 139 | SHARED LIBRARY VERSIONING |
140 | ||
141 | [this section is at the moment just gdt's opinion] | |
142 | ||
143 | Quagga builds several shared libaries (lib/libzebra, ospfd/libospf, | |
144 | ospfclient/libsopfapiclient). These may be used by external programs, | |
145 | e.g. a new routing protocol that works with the zebra daemon, or | |
146 | ospfapi clients. The libtool info pages (node Versioning) explain | |
147 | when major and minor version numbers should be changed. These values | |
148 | are set in Makefile.am near the definition of the library. If you | |
149 | make a change that requires changing the shared library version, | |
150 | please update Makefile.am. | |
151 | ||
152 | libospf exports far more than it should, and is needed by ospfapi | |
153 | clients. Only bump libospf for changes to functions for which it is | |
154 | reasonable for a user of ospfapi to call, and please err on the side | |
155 | of not bumping. | |
156 | ||
157 | There is no support intended for installing part of zebra. The core | |
158 | library libzebra and the included daemons should always be built and | |
159 | installed together. | |
160 | ||
74a2dd7b | 161 | |
d9fd04c2 | 162 | PATCH SUBMISSION |
163 | ||
85cf0a0d | 164 | * Send a clean diff against the head of CVS in unified diff format, eg by: |
e69b9e40 | 165 | cvs <cvs opts> diff -upwb .... |
d9fd04c2 | 166 | |
167 | * Include ChangeLog and NEWS entries as appropriate before the patch | |
6a524706 | 168 | (or in it if you are 100% up to date). A good ChangeLog makes it easier to |
169 | review a patch, hence failure to include a good ChangeLog is prejudicial | |
170 | to proper review of the patch, and hence the possibility of inclusion. | |
d9fd04c2 | 171 | |
18323bb2 | 172 | * Include only one semantic change or group of changes per patch. |
d9fd04c2 | 173 | |
85cf0a0d | 174 | * Do not make gratuitous changes to whitespace. See the w and b arguments |
175 | to diff. | |
d9fd04c2 | 176 | |
177 | * State on which platforms and with what daemons the patch has been | |
178 | tested. Understand that if the set of testing locations is small, | |
179 | and the patch might have unforeseen or hard to fix consequences that | |
180 | there may be a call for testers on quagga-dev, and that the patch | |
181 | may be blocked until test results appear. | |
182 | ||
183 | If there are no users for a platform on quagga-dev who are able and | |
184 | willing to verify -current occasionally, that platform may be | |
185 | dropped from the "should be checked" list. | |
186 | ||
74a2dd7b | 187 | |
d9fd04c2 | 188 | PATCH APPLICATION TO CVS |
189 | ||
190 | * Only apply patches that meet the submission guidelines. | |
191 | ||
192 | * If a patch is large (perhaps more than 100 new/changed lines), tag | |
193 | the repository before and after the change with e.g. before-foo-fix | |
194 | and after-foo-fix. | |
195 | ||
196 | * If the patch might break something, issue a call for testing on the | |
197 | mailinglist. | |
198 | ||
4134ceb7 | 199 | * Give an appropriate commit message, eg the ChangeLog entry should suffice, |
1f8f61a7 | 200 | if it does not, then the ChangeLog entry itself needs to be corrected. The |
201 | commit message text should be identical to that added to the ChangeLog | |
202 | message. (One suggestion: when commiting, use your editor to read in the | |
203 | ChangeLog and delete all previous ChangeLogs.) | |
4134ceb7 | 204 | |
d9fd04c2 | 205 | * By committing a patch, you are responsible for fixing problems |
206 | resulting from it (or backing it out). | |
207 | ||
74a2dd7b | 208 | |
d9fd04c2 | 209 | STABLE PLATFORMS AND DAEMONS |
210 | ||
211 | The list of platforms that should be tested follow. This is a list | |
212 | derived from what quagga is thought to run on and for which | |
213 | maintainers can test or there are people on quagga-dev who are able | |
214 | and willing to verify that -current does or does not work correctly. | |
215 | ||
216 | BSD (Free, Net or Open, any platform) # without capabilities | |
217 | GNU/Linux (any distribution, i386) | |
1f8f61a7 | 218 | Solaris (strict alignment, any platform) |
18323bb2 | 219 | [future: NetBSD/sparc64] |
d9fd04c2 | 220 | |
221 | The list of daemons that are thought to be stable and that should be | |
222 | tested are: | |
223 | ||
224 | zebra | |
225 | bgpd | |
226 | ripd | |
227 | ospfd | |
228 | ripngd | |
1f431d2d | 229 | |
18323bb2 | 230 | Daemons which are in a testing phase are |
231 | ||
232 | ospf6d | |
233 | isisd | |
8035e9f0 | 234 | watchquagga |
18323bb2 | 235 | |
74a2dd7b | 236 | |
9e867fe6 | 237 | IMPORT OR UPDATE VENDOR SPECIFIC ROUTING PROTOCOLS |
238 | ||
239 | The source code of Quagga is based on two vendors: | |
240 | ||
241 | zebra_org (http://www.zebra.org/) | |
242 | isisd_sf (http://isisd.sf.net/) | |
243 | ||
18323bb2 | 244 | [20041105: Is isisd.sf.netf still where isisd word is happening, or is |
245 | the quagga repo now the canonical place? The last tarball on sf is | |
246 | two years old. --gdt] | |
247 | ||
9e867fe6 | 248 | In order to import source code, the following procedure should be used: |
249 | ||
250 | * Tag the Current Quagga CVS repository: | |
251 | ||
252 | cvs tag import_isisd_sf_20031223 | |
253 | ||
254 | * Import the source code into the Quagga's framework. You must not modified | |
255 | this source code. It will be merged later. | |
256 | ||
257 | cd dir_isisd | |
258 | export CVSROOT=:pserver:LOGIN@anoncvs.quagga.net:/var/cvsroot | |
259 | cvs import quagga/isisd isisd_sf isisd_sf_20031223 | |
260 | ---COMMENTS--- | |
261 | Vendor: [isisd_sf] Sampo's ISISd from Sourceforge | |
262 | Tag: [isisd_sf_20031217] Current CVS release | |
263 | --- | |
264 | ||
265 | * Update your Quagga's directory: | |
266 | ||
267 | cd dir_quagga | |
268 | cvs update -dP | |
269 | ||
270 | or | |
271 | ||
272 | cvs co -d quagga_isisd quagga | |
273 | ||
274 | * Merge the code, then commit: | |
275 | ||
276 | cvs commit | |
277 |