BIND 10 master, updated. fdc7dd1164fad1d1ccd45b2713a231e0434dda08 [master] Merge branch 'trac3109' (Contributor's Guide)
BIND 10 source code commits
bind10-changes at lists.isc.org
Fri Dec 6 19:03:51 UTC 2013
The branch, master has been updated
via fdc7dd1164fad1d1ccd45b2713a231e0434dda08 (commit)
via 016bfae00460b4f88adbfd07ed26759eb294ef10 (commit)
via ae4ce59aabd5281822630668956425fa6167eca8 (commit)
via 342c56224c215ca1cb245df0875878e4f8fad0e6 (commit)
via 273b3105e21cfa457381983bf0c98f2590c55ebd (commit)
via e2dbd7090ae49267e0ff14f593de49629afbf710 (commit)
via f83c6c44a65b4cb04d3e2691e5bf0a3bf82d59c0 (commit)
via 3b9c90d00e5b0c2790a9d7c94b8765b61a6b64a0 (commit)
via 1e278e019742e8f13b93d6f670d50eb14e675217 (commit)
via 677e0bd0a52306ea81f3a7bab51257ffc466b856 (commit)
via 2f3324cbeeada97f94105d9c8ce902f496e34dd3 (commit)
via 37bb1f516ee852871f61b92d7bb5f50ba79a4b0f (commit)
via 19cb9064139e3b2adcf26bef7d7fdd38db356010 (commit)
via 3f5af01217a8e67822a9a25744b06579390a57f5 (commit)
via 8bf74aab112eeac3471cc9d9ebdfb74cac970176 (commit)
via 7d35d92626c35bd28ba4cf195fb679f44091bf6b (commit)
via d640e2711d36ff59c9adf84b092ccba7f17ef46a (commit)
via 0e24ff0516f95c8f0ae4a4b82892d97e40891530 (commit)
via 14aecfe2eb61e067200a91684eec7b04b10e0634 (commit)
via 08d4a94ef93b4a1fb0ba0fcbadc3793793c8c73a (commit)
via e674965bfb4fefd24fd44b70e80429ddea92e6ca (commit)
via e18f0aeceb9095198c3081cbd08e772a5715baf8 (commit)
via 2f326350f8f49fd6db247d38d6c3575e9e82a0a5 (commit)
via d2b3d82dc02b9e6fe5fab81b78f6dfc532888d3b (commit)
via 46e6d05e9f1c6990c17afff7890607db8c5acc04 (commit)
via cfd7033c2710b19d92d719f54ceb50fe866261bc (commit)
via 8ce7f740b84364774d90f3438634577cc556ae66 (commit)
via 9b5c746e9bf6fe264f4aa57dc0e884f4fd5a8d85 (commit)
from 1391bf812cb841eabca6a7e5f67fc0324367eac1 (commit)
Those revisions listed above that are new to this repository have
not appeared on any other notification email; so we list those
revisions in full, below.
- Log -----------------------------------------------------------------
commit fdc7dd1164fad1d1ccd45b2713a231e0434dda08
Merge: 1391bf8 016bfae
Author: Tomek Mrugalski <tomasz at isc.org>
Date: Fri Dec 6 20:03:23 2013 +0100
[master] Merge branch 'trac3109' (Contributor's Guide)
Conflicts:
ChangeLog
-----------------------------------------------------------------------
Summary of changes:
ChangeLog | 4 ++
doc/devel/contribute.dox | 162 ++++++++++++++++++++++++++++++++++++++++++++++
doc/devel/mainpage.dox | 4 ++
3 files changed, 170 insertions(+)
create mode 100644 doc/devel/contribute.dox
-----------------------------------------------------------------------
diff --git a/ChangeLog b/ChangeLog
index 658f218..36fe67f 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 0000000..9103bed
--- /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.
+
+ at 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 at conference.jabber.isc.org). Those involved in DHCP also use
+the \c dhcp chatroom (xmpp:dhcp at 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.
+
+ at 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:
+
+ at code
+./configure --with-gtest=/path/to/your/gtest/dir
+ at endcode
+
+or
+
+ at code
+./configure --with-gtest-source=/path/to/your/gtest/dir
+ at 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:
+
+ at code
+make check
+ at 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:
+
+ at code
+make distcheck
+ at 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:
+
+ at code
+ ./configure --help
+ at endcode
+
+ at 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.
+
+ at 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 dd210f3..4110b26 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
* <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
More information about the bind10-changes
mailing list