diff --git a/ChangeLog b/ChangeLog index 658f218bc5..36fe67f601 100644 --- a/ChangeLog +++ b/ChangeLog @@ -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 diff --git a/doc/devel/contribute.dox b/doc/devel/contribute.dox new file mode 100644 index 0000000000..9103bedd7d --- /dev/null +++ b/doc/devel/contribute.dox @@ -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. + +*/ diff --git a/doc/devel/mainpage.dox b/doc/devel/mainpage.dox index dd210f38db..4110b26550 100644 --- a/doc/devel/mainpage.dox +++ b/doc/devel/mainpage.dox @@ -36,6 +36,10 @@ * * Regardless of your field of expertise, you are encouraged to visit the * BIND10 webpage (http://bind10.isc.org) + * + * @section contrib Contributor's Guide + * - @subpage contributorGuide + * * @section hooksFramework Hooks Framework * - @subpage hooksdgDevelopersGuide * - @subpage dhcpv4Hooks