|
|
@@ -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.
|
|
|
+
|
|
|
+*/
|
Tomek Mrugalski