contribute.dox 6.79 KB
Newer Older
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
// Copyright (C) 2013  Internet Systems Consortium, Inc. ("ISC")
//
// Permission to use, copy, modify, and/or distribute this software for any
// purpose with or without fee is hereby granted, provided that the above
// copyright notice and this permission notice appear in all copies.
//
// THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
// REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
// AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
// INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
// LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
// OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
// PERFORMANCE OF THIS SOFTWARE.

/**

 @page contributorGuide BIND10 Contributor's Guide

19
So you found a bug in BIND10 or plan to develop an extension and want to
20
21
22
send a patch? Great! This page will explain how to contribute your
changes and not get disappointed in the process.

23
24
@section contributorGuideWritePatch Writing a patch

25
Before you start working on a patch or a new feature, it is a good idea
26
27
to discuss it first with BIND10 developers. You can post your questions
to the \c bind10-dev mailing list
28
(https://lists.isc.org/mailman/listinfo/bind10-dev) for general BIND10
Mukund Sivaraman's avatar
Mukund Sivaraman committed
29
stuff, or to the \c bind10-dhcp mailing list
30
(https://lists.isc.org/mailman/listinfo/bind10-dhcp) for DHCP specific
31
topics. If you prefer to get faster feedback, most BIND10 developers
Mukund Sivaraman's avatar
Mukund Sivaraman committed
32
hang out in the \c bind10 jabber room
33
34
35
36
37
38
(xmpp:bind10@conference.jabber.isc.org). Those involved in DHCP also use
the \c dhcp chatroom (xmpp:dhcp@conference.jabber.isc.org). Feel free to
join these rooms and talk to us. It is possible that someone else is
working on your specific issue or perhaps the solution you plan to
implement is not the best one. Often having a 10 minute talk could save
many hours of engineering work.
39

40
41
42
43
44
45
First step would be to get the source code from our Git repository. The
procedure is very easy and is explained here:
http://bind10.isc.org/wiki/GitGuidelines.  While it is possible to
provide a patch against the latest stable release, it makes the review
process much easier if it is for latest code from the Git \c master
branch.
46

47
48
49
50
51
52
53
54
55
Ok, so you have a patch? Great! Before you submit it, make sure that
your code compiles. This may seem obvious, but it there's more to
it. I'm sure you have checked that it compiles on your system, but
BIND10 is a portable software. Besides Linux, it is being compiled on
relatively uncommon systems, like OpenBSD or Solaris 11. Will your
code compile there? Will it work? What about endianess? It is likely
that you used regular x86, but the software is expected to run on many
other architectures.

56
Does your patch conforms to BIND10
57
58
59
60
61
62
63
http://bind10.isc.org/wiki/CodingGuidelines? You still can submit
a patch that does not adhere to it, but it will decrease your
chances of being accepted. If the deviations are minor, ISC engineer
that will do the review, will likely fix the issues. However,
if there are lots of them, reviewer may simply reject the patch
and ask you to fix it, before resubmitting.

64
65
@section contributorGuideUnittests Running unit-tests

66
67
68
69
70
71
One of the ground rules in BIND10 development is that every piece of
code has to be tested. We now have an extensive set of unit-tests for
almost every line of code. Even if you are fixing something small,
like a single line fix, it is encouraged to write unit-test for that
change. That is even more true for new code. If you write a new
function, method or a class, you definitely should write unit-tests
72
for it.
73
74
75
76
77
78

BIND10 uses google test (gtest) framework as a base for our
unit-tests. See http://code.google.com/p/googletest/ for details.
You must have gtest installed or at least compiled before compiling
BIND10 unit-tests. To enable unit-tests in BIND10

79
@code
80
./configure --with-gtest=/path/to/your/gtest/dir
81
@endcode
82

83
or
84

85
@code
86
./configure --with-gtest-source=/path/to/your/gtest/dir
87
88
89
90
91
92
93
94
95
96
97
98
99
100
@endcode

There are other useful switches passed to configure. It is always a good
idea to use --enable-logger-checks, which does sanity checks on logger
parameters. If you happen to modify anything in the documentation, use
--enable-generate-docs. If you are modifying DHCP code, you are likely
to be interested in MySQL backend for DHCP. Keep note that if the backend
is not enabled, MySQL specific unit-tests are skipped, too. From that
perspective, it is useful to use --with-dhcp-mysql parameter. For a
complete list of all switches, use:

@code
 ./configure --help
@endcode
101
102
103
104
105

Depending on how you compiled or installed (e.g. from sources or using
some package management system) one of those two switches will find
gtest. After that you make run unit-tests:

106
@code
107
make check
108
@endcode
109
110
111
112

If you happen to add new files or modified Makefiles, it is also a
good idea to check if you haven't broken distribution process:

113
@code
114
make distcheck
115
116
117
@endcode

@section contributorGuideReview Going through a review
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142

Once all those are checked and working, feel free to create a ticket
for your patch (http://bind10.isc.org) or attach your patch to the
existing ticket if there is one. You may drop a note to bind10 or dhcp
chatroom saying that you have submitted a patch. Alternatively, you
may send a note to bind10-dev or bind10-dhcp lists.

Here's the tricky part. One of BIND10 developers will review your
patch, but it may not happen immediately. Unfortunately, developers
are usually working under tight schedule, so any extra unplanned
review work sometimes make take a while. Having said that, we value
external contributions very much and will do whatever we can to
review patches in a timely manner. Don't get discouraged if your
patch is not accepted after first review. To keep the code quality
high, we use the same review processes for internal code and for
external patches. It may take several cycles of review/updated patch
submissions before the code is finally accepted.

Once the process is almost completed, the developer will likely ask
you how you would like to be credited. The typical answers are by
first,last name, by nickname, by company or anonymously. Typically we
will add a note to ChangeLog. If the contributted feature is big or
critical for whatever reason, it may be also mentioned in release
notes.

143
144
145
146
147
148
149
150
151
152
153
@section contributorGuideExtra Extra steps

If you are interested in even more in-depth testing, you are welcome
to visit BIND10 build farm: http://git.bind10.isc.org/~tester/builder/builder-new.html
This is a life result page with all tests being run on various systems.
Besides basic unit-tests, we also run them with valgrind (memory debugger),
with cppcheck and scan-build (static code analyzers), Lettuce system tests
and more. Although it is not possible for non ISC employees to run tests
on that farm, it is possible that your contributed patch will end up there
sooner or later.

154
*/