ISC welcomes community code submissions. This document is intended to help you, the code contributor, ensure that your submission is likely to make it into a released version of BIND 9.
We do not blindly accept code submissions. We not only check each submission for technical standards, we also rate its merit as a feature or change to the BIND 9 system. Not all suggested features make it into code even if the code is provided to us; ISC responsible for maintaining high quality code and features.
When you decide a feature needs to be implemented, it is generally a good idea to discuss it with other developers. There is a list called bind-workers which developers are encouraged to subscribe to. Sending mail here may help you gauge interest in the feature, and perhaps even find people interested in assisting with the feature or change you propose.
You are likely to get a response to a bind-workers message, but if you do not, please open a ticket in the firstname.lastname@example.org ticket system. This is a direct communication path to our support staff and developers. Opening this ticket allows us to work together more easily and keep a journal of communications.
You want to include in this ticket, at a minimum:
- What is the purpose of this new feature?
- What problems does it solve?
- Why would others want this feature?
If the submission is a fix for a defect, include things like:
- How can the defect be triggered?
- How does the submitted code correct this defect?
- What unit and system tests are included?
Working with ISC
Depending on the size of the code submission, we may pair an ISC developer with you. This gives you a helping hand to ensure that the the final code is in a state that it can be accepted. This person will help with the technical guidelines as well as assisting on the non-technical side. They will be a resource for questions you may have while working on the feature. They are not here to write code, tests, or documentation for you; you as the code submitter are the author.
What to Expect From ISC
- Before your code is accepted, expect us to give suggestions, comments, and requirements to you as you work on the code. This is why contacting us early is very important, especially if this is your first code submission.
- Expect us to spend time proportional to the importance we place on the feature. Features which benefit the largest user community will always be more important to us, and less important features may have less ISC resources assigned to them.
- In some cases, we may request funding to continue to maintain contributed code. Once it's added to our code base, in the main distribution, we incur a cost. We will not always request this, but our resources are limited and our software open source.
What ISC Expects From You
- Solid, clean code contributions.
- Responsiveness to our comments and suggestions.
- Understanding that not every feature is as important to you as it is to us, or others.
- Good automated tests written for our automated testing tools.
- Operating system independence, unless a feature is only available on specific operating systems.
- Comments and documentation to be well written English, and not contain slights or other comments about unfavorable operating systems, DNS clients, or other DNS servers.
Guidelines, Metrics, and Acceptance
ISC will review your submission at least once, at the end. Depending on the size and how much iteration is needed to get the code into a working state, we may review it at other times. Our review is both technical and non-technical. We may provide feedback on your following the BIND 9 Code Style Guide or on test coverage. We may provide feedback on what would assist us in accepting your work more easily and quickly.
BIND 9 uses a Test Driven Development model for all new code. In our use of TDD, a test is written to cover a broad functional change, and the test is run. It will fail. The code is then written to make the test pass, and only enough to make it pass. This is an iterative process. Generally many tests are written as a general function is developed, but the test is always written just before writing code. As you dig deeper into more specific code with more specific tests, some will start to pass, and eventually all tests will pass.
BIND 9 requires tests. This is, unfortunately, a fairly new requirement. However, unit tests should be provided to exercise your new code as well as previous functionality. This is especially important when changing an existing feature to have new functionality. It must be shown that the previous feature is covered by a test, and that the new functionality works as expected.
It is not acceptable to show that running a series of commands works; it must be something run under our automated unit or system test scripts. This is generally not optional. If you feel writing a test is truly impossible, you'll need to justify it. It isn't sufficient that it's merely hard or inconvenient.
While ISC uses TDD, it is not strictly required that you do to successfully submit code to ISC. We can tell the difference, however, and do prefer a true TDD methodology.
Your code should contain sufficient comments, notes, and other information to make it understandable by a wide audience. This is also a form of communication between you and ISC, and later between others who touch your code. It is often omitted, but good technical, "here's the approach I took" documentation assists all future developers, including ISC developers.
It should describe why decisions were made, when necessary. It should include potential future improvement points, where an algorithm was chosen based on suspected or known sizing but may be a bottleneck in the future, and any other relevant coder to coder communication.
This form of documentation is not a substitute for user-facing documentation. In most cases this is also needed for feature changes.
BIND 9 has a C code style guide. Following this as closely as possible is advised. Code which deviates too much will require time on ISC's end to reformat, or it may be outright rejected until it is corrected.
While there are no guidelines on function length, there is a practical limit on how much code can fit into a single function and still be testable. Don't use existing code as a guideline here. Unit testing a 500 line function is not practical, and there are plenty of legacy examples of too-long functions inside BIND 9.
If necessary, feel free to refactor code (preferably with pinning tests) to improve testability before you start on the actual feature.
If needed, please provide a suggested change to the BIND 9 Administrator's Reference Manual (ARM). There may be other user-facing documentation included as needed, such as a how-to guide, sample configurations, graphics, etc. These would likely appear on the ISC knowledge base rather than inside the ARM.
In general, we prefer a copyright assignment to ISC. Regardless of the assignment, however, the code must have a compatible license. GNU Public License is incompatible with the ISC license, and any code with the GPL or other incompatible licenses will be rejected without further review.
© 2001-2017 Internet Systems ConsortiumFor assistance with problems and questions for which you have not been able to find an answer in our Knowledge Base, we recommend searching our community mailing list archives and/or posting your question there (you will need to register there first for your posts to be accepted). The bind-users and the dhcp-users lists particularly have a long-standing and active membership.ISC relies on the financial support of the community to fund the development of its open source software products. If you would like to support future product evolution and maintenance as well having peace of mind knowing that our team of experts are poised to provide you with individual technical assistance whenever you call upon them, then please consider our Professional Subscription Support services - details can be found on our main website.