// 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 and not get disappointed in the process. @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. Does your patch conform to BIND10 ? 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 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 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: @code make check @endcode 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: @code make distcheck @endcode @section contributorGuideReview Going through a review 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. @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. */