mirror of
https://gitlab.isc.org/isc-projects/kea
synced 2025-08-29 04:57:52 +00:00
[master] Merge branch 'trac3109' (Contributor's Guide)
Conflicts: ChangeLog
This commit is contained in:
Tomek Mrugalski
commit
fdc7dd1164
@ -1,3 +1,7 @@
|
||||
714. [doc] tomek
|
||||
BIND10 Contributor's Guide added.
|
||||
(Trac #3109, git 016bfae00460b4f88adbfd07ed26759eb294ef10)
|
||||
|
||||
713. [func] tmark
|
||||
Added DNS update request construction to d2::NameAddTransaction in
|
||||
b10-dhcp-ddns. The class now generates all DNS update request variations
|
||||
|
||||
162
doc/devel/contribute.dox
Normal file
162
doc/devel/contribute.dox
Normal file
@ -0,0 +1,162 @@
|
||||
// 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
|
||||
|
||||
So you found a bug in BIND10 or plan to develop an extension and want to
|
||||
send a patch? Great! This page will explain how to contribute your
|
||||
changes smoothly.
|
||||
|
||||
@section contributorGuideWritePatch Writing a patch
|
||||
|
||||
Before you start working on a patch or a new feature, it is a good idea
|
||||
to discuss it first with BIND10 developers. You can post your questions
|
||||
to the \c bind10-dev mailing list
|
||||
(https://lists.isc.org/mailman/listinfo/bind10-dev) for general BIND10
|
||||
stuff, or to the \c bind10-dhcp mailing list
|
||||
(https://lists.isc.org/mailman/listinfo/bind10-dhcp) for DHCP specific
|
||||
topics. If you prefer to get faster feedback, most BIND10 developers
|
||||
hang out in the \c bind10 jabber room
|
||||
(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.
|
||||
|
||||
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.
|
||||
|
||||
Ok, so you have written a patch? Great! Before you submit it, make sure
|
||||
that your code compiles. This may seem obvious, but there's more to
|
||||
it. You have surely checked that it compiles on your system, but BIND10
|
||||
is portable software. Besides Linux, it is compiled and used on
|
||||
relatively uncommon systems like OpenBSD and Solaris 11. Will your code
|
||||
compile and work there? What about endianess? It is likely that you used
|
||||
a regular x86 architecture machine to write your patch, but the software
|
||||
is expected to run on many other architectures. You may take a look at
|
||||
system specific build notes (http://bind10.isc.org/wiki/SystemSpecificNotes).
|
||||
For a complete list of systems we build on, you may take a look at the
|
||||
following build farm report: http://git.bind10.isc.org/~tester/builder/builder-new.html .
|
||||
|
||||
Does your patch conform to BIND10 coding guidelines
|
||||
(http://bind10.isc.org/wiki/CodingGuidelines)? You still can submit a
|
||||
patch that does not adhere to it, but that will decrease its chances of
|
||||
being accepted. If the deviations are minor, the BIND10 engineer who
|
||||
does the review will likely fix the issues. However, if there are lots
|
||||
of issues, the reviewer may simply reject the patch and ask you to fix
|
||||
it before re-submitting.
|
||||
|
||||
@section contributorGuideUnittests Running unit-tests
|
||||
|
||||
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-tests 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
|
||||
for it.
|
||||
|
||||
BIND10 uses the Google C++ Testing Framework (also called googletest or
|
||||
gtest) as a base for our C++ unit-tests. See
|
||||
http://code.google.com/p/googletest/ for details. For Python unit-tests,
|
||||
we use the its \c unittest library which is included in Python. You must
|
||||
have \c gtest installed or at least extracted in a directory before
|
||||
compiling BIND10 unit-tests. To enable unit-tests in BIND10, use:
|
||||
|
||||
@code
|
||||
./configure --with-gtest=/path/to/your/gtest/dir
|
||||
@endcode
|
||||
|
||||
or
|
||||
|
||||
@code
|
||||
./configure --with-gtest-source=/path/to/your/gtest/dir
|
||||
@endcode
|
||||
|
||||
Depending on how you compiled or installed \c gtest (e.g. from sources
|
||||
or using some package management system) one of those two switches will
|
||||
find \c gtest. After that you make run unit-tests:
|
||||
|
||||
@code
|
||||
make check
|
||||
@endcode
|
||||
|
||||
If you happen to add new files or have modified any \c Makefile.am
|
||||
files, it is also a good idea to check if you haven't broken the
|
||||
distribution process:
|
||||
|
||||
@code
|
||||
make distcheck
|
||||
@endcode
|
||||
|
||||
There are other useful switches which can be passed to configure. It is
|
||||
always a good idea to use \c --enable-logger-checks, which does sanity
|
||||
checks on logger parameters. If you happen to modify anything in the
|
||||
documentation, use \c --enable-generate-docs. If you are modifying DHCP
|
||||
code, you are likely to be interested in enabling the MySQL backend for
|
||||
DHCP. Note that if the backend is not enabled, MySQL specific unit-tests
|
||||
are skipped. From that perspective, it is useful to use
|
||||
\c --with-dhcp-mysql. For a complete list of all switches, use:
|
||||
|
||||
@code
|
||||
./configure --help
|
||||
@endcode
|
||||
|
||||
@section contributorGuideReview Going through a review
|
||||
|
||||
Once all those are checked and working, feel free to create a ticket for
|
||||
your patch at http://bind10.isc.org/ or attach your patch to an existing
|
||||
ticket if you have fixed it. It would be nice if you also join the
|
||||
\c bind10 or \c dhcp chatroom saying that you have submitted a
|
||||
patch. Alternatively, you may send a note to the \c bind10-dev or
|
||||
\c bind10-dhcp mailing 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 a tight schedule, so any extra unplanned review work may
|
||||
take a while sometimes. 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
|
||||
some cycles of review/updated patch submissions before the code is
|
||||
finally accepted.
|
||||
|
||||
Once the process is almost complete, the developer will likely ask you
|
||||
how you would like to be credited. The typical answers are by first and
|
||||
last name, by nickname, by company name or anonymously. Typically we
|
||||
will add a note to the \c ChangeLog and also set you as the author of
|
||||
the commit applying the patch. If the contributted feature is big or
|
||||
critical for whatever reason, it may also be mentioned in release notes.
|
||||
|
||||
@section contributorGuideExtra Extra steps
|
||||
|
||||
If you are interested in knowing the results of more in-depth testing,
|
||||
you are welcome to visit the BIND10 build farm:
|
||||
http://git.bind10.isc.org/~tester/builder/builder-new.html. This is a
|
||||
live result page with all tests being run on various systems. Besides
|
||||
basic unit-tests, we also have reports from Valgrind (memory debugger),
|
||||
cppcheck and clang-analyzer (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.
|
||||
|
||||
*/
|
||||
@ -36,6 +36,10 @@
|
||||
*
|
||||
* Regardless of your field of expertise, you are encouraged to visit the
|
||||
* <a href="http://bind10.isc.org/">BIND10 webpage (http://bind10.isc.org)</a>
|
||||
*
|
||||
* @section contrib Contributor's Guide
|
||||
* - @subpage contributorGuide
|
||||
*
|
||||
* @section hooksFramework Hooks Framework
|
||||
* - @subpage hooksdgDevelopersGuide
|
||||
* - @subpage dhcpv4Hooks
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user