kea/doc/devel/contribute.dox

// Copyright (C) 2013,2015  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 Kea Contributor's Guide

So you found a bug in Kea 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 Kea developers. You can post your
questions to the \c kea-dev mailing list
(https://lists.isc.org/mailman/listinfo/kea-dev) or kea-users
(https://lists.isc.org/mailman/listinfo/kea-users). The kea-users list
is intended for users who are not interested in the internal workings
or development details of Kea: it is OK to ask for feedback regarding new
design or the best proposed solution to a certain problem, but all
the internal details should be discussed on kea-dev and not posted
to kea-users.

If you prefer to get
faster feedback, most Kea developers hang out in the \c dhcp
jabber room (xmpp:dhcp@conference.jabber.isc.org). Feel free to join this
room 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.

The first step in writing the patch or new feature should be to get
the source code from our Git repository. The procedure is very easy and
is explained here: http://kea.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 Kea
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://kea.isc.org/wiki/SystemSpecificNotes).
For a complete list of systems we build on, you may take a look at the
following build farm report: https://jenkins.isc.org/view/Kea_BuildFarm/ .

Does your patch conform to Kea coding guidelines
(http://kea.isc.org/wiki/CodingGuidelines)? You can submit a
patch that does not adhere to them, but that will reduce its chances of
being accepted. If the deviations are minor, the Kea 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 Kea 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, you are 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.

To ensure that everything is tested, ISC uses a development method
called Test Driven Development (TDD).  In TDD, a feature is developed
alongside the tests, with the tests being written first.  In detail,
a test is written for a small piece of functionality and run against
the existing code. (In the case where the test is a unit test for
a function, it would be run against an empty (unimplemented)
function.)  The test should fail.  A minimal amount of code is then
written, just enough to get the test to pass.  Then the process is
repeated for the next small piece of functionality. This continues
until all the functionality has been implemented.

This approach has two advantages:

- By writing a test first and then only enough code to pass the
test, that code is fully tested.  By repeating this process until
the feature is fully implemented, all the code gets test coverage.
You avoid the situation where not enough tests have been written
to check all the code.

- By running the test before the code implementing the function is
written and observing the test fail, you can detect the situation
where a bug in the test code will cause it to pass regardless of
the code being tested.

See @ref qaUnitTests for instructions on how to run unit-tests.

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. Use \c --enable-debug to enable various
additional consistency checks that reduce performance but help during
development. 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 a non-default database
backends for DHCP. Note that if the backend is not enabled,
the database-specific unit-tests are skipped. To enable the MySQL backend,
use the switch \c --with-dhcp-mysql; for PostgreSQL, use \c --with-dhcp-pgsql.
A complete list of all switches can be obtained with the command:

@code
 ./configure --help
@endcode

@section contributorGuideReview Going through a review

Once everything is checked and working, feel free to create a ticket for
your patch at http://kea.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 dhcp chatroom saying that you have submitted a patch. Alternatively,
you may send a note to the \c kea-dev mailing list.

Here's the tricky part. One of Kea 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 external patches as we do for internal code. It may take
some cycles of review/updated patch submissions before the code is
finally accepted. The nature of the review process is that it emphasizes
areas that need improvement. If you are not used to the review process,
you may get the impression that the feedback is negative. It is not: even
the Kea developers seldom see reviews that say "All OK please merge".

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 contributed 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 ISC Jenkins page: https://jenkins.isc.org
(Our old Kea build farm http://git.kea.isc.org/~tester/builder/KEA-builder-new.html
is being migrated to Jenkins).  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. We also have ISC Forge tests running, but currently
the test results are not publicly available.

*/