|
Packit |
5ce601 |
CONTRIBUTING
|
|
Packit |
5ce601 |
|
|
Packit |
5ce601 |
BIND Source Access and Contributor Guidelines
|
|
Packit |
5ce601 |
|
|
Packit |
5ce601 |
Feb 22, 2018
|
|
Packit |
5ce601 |
|
|
Packit |
5ce601 |
Contents
|
|
Packit |
5ce601 |
|
|
Packit |
5ce601 |
1. Access to source code
|
|
Packit |
5ce601 |
2. Reporting bugs
|
|
Packit |
5ce601 |
3. Contributing code
|
|
Packit |
5ce601 |
|
|
Packit |
5ce601 |
Introduction
|
|
Packit |
5ce601 |
|
|
Packit |
5ce601 |
Thank you for using BIND!
|
|
Packit |
5ce601 |
|
|
Packit |
5ce601 |
BIND is open source software that implements the Domain Name System (DNS)
|
|
Packit |
5ce601 |
protocols for the Internet. It is a reference implementation of those
|
|
Packit |
5ce601 |
protocols, but it is also production-grade software, suitable for use in
|
|
Packit |
5ce601 |
high-volume and high-reliability applications. It is by far the most
|
|
Packit |
5ce601 |
widely used DNS software, providing a robust and stable platform on top of
|
|
Packit |
5ce601 |
which organizations can build distributed computing systems with the
|
|
Packit |
5ce601 |
knowledge that those systems are fully compliant with published DNS
|
|
Packit |
5ce601 |
standards.
|
|
Packit |
5ce601 |
|
|
Packit |
5ce601 |
BIND is and will always remain free and openly available. It can be used
|
|
Packit |
5ce601 |
and modified in any way by anyone.
|
|
Packit |
5ce601 |
|
|
Packit |
5ce601 |
BIND is maintained by the Internet Systems Consortium, a public-benefit
|
|
Packit |
5ce601 |
501(c)(3) nonprofit, using a "managed open source" approach: anyone can
|
|
Packit |
5ce601 |
see the source, but only ISC employees have commit access. Until recently,
|
|
Packit |
5ce601 |
the source could only be seen once ISC had published a release: read
|
|
Packit |
5ce601 |
access to the source repository was restricted just as commit access was.
|
|
Packit |
5ce601 |
That's now changing, with the opening of a public git mirror to the BIND
|
|
Packit |
5ce601 |
source tree (see below).
|
|
Packit |
5ce601 |
|
|
Packit |
5ce601 |
Access to source code
|
|
Packit |
5ce601 |
|
|
Packit |
5ce601 |
Public BIND releases are always available from the ISC FTP site.
|
|
Packit |
5ce601 |
|
|
Packit |
5ce601 |
A public-access GIT repository is also available at https://gitlab.isc.org
|
|
Packit |
5ce601 |
. This repository is a mirror, updated several times per day, of the
|
|
Packit |
5ce601 |
source repository maintained by ISC. It contains all the public release
|
|
Packit |
5ce601 |
branches; upcoming releases can be viewed in their current state at any
|
|
Packit |
5ce601 |
time. It does not contain development branches or unreviewed work in
|
|
Packit |
5ce601 |
progress. Commits which address security vulnerablilities are withheld
|
|
Packit |
5ce601 |
until after public disclosure.
|
|
Packit |
5ce601 |
|
|
Packit |
5ce601 |
You can browse the source online via https://gitlab.isc.org/isc-projects/
|
|
Packit |
5ce601 |
bind9
|
|
Packit |
5ce601 |
|
|
Packit |
5ce601 |
To clone the repository, use:
|
|
Packit |
5ce601 |
|
|
Packit |
5ce601 |
$ git clone https://gitlab.isc.org/isc-projects/bind9.git
|
|
Packit |
5ce601 |
|
|
Packit |
5ce601 |
Release branch names are of the form v9_X, where X represents the second
|
|
Packit |
5ce601 |
number in the BIND 9 version number. So, to check out the BIND 9.12
|
|
Packit |
5ce601 |
branch, use:
|
|
Packit |
5ce601 |
|
|
Packit |
5ce601 |
$ git checkout v9_12
|
|
Packit |
5ce601 |
|
|
Packit |
5ce601 |
Whenever a branch is ready for publication, a tag will be placed of the
|
|
Packit |
5ce601 |
form v9_X_Y. The 9.12.0 release, for instance, is tagged as v9_12_0.
|
|
Packit |
5ce601 |
|
|
Packit |
5ce601 |
The branch in which the next major release is being developed is called
|
|
Packit |
5ce601 |
master.
|
|
Packit |
5ce601 |
|
|
Packit |
5ce601 |
Reporting bugs
|
|
Packit |
5ce601 |
|
|
Packit |
5ce601 |
Reports of flaws in the BIND package, including software bugs, errors in
|
|
Packit |
5ce601 |
the documentation, missing files in the tarball, suggested changes or
|
|
Packit |
5ce601 |
requests for new features, etc, can be filed using https://gitlab.isc.org/
|
|
Packit |
5ce601 |
isc-projects/bind9/issues.
|
|
Packit |
5ce601 |
|
|
Packit |
5ce601 |
Due to a large ticket backlog, we are sometimes slow to respond,
|
|
Packit |
5ce601 |
especially if a bug is cosmetic or if a feature request is vague or low in
|
|
Packit |
5ce601 |
priority, but we will try at least to acknowledge legitimate bug reports
|
|
Packit |
5ce601 |
within a week.
|
|
Packit |
5ce601 |
|
|
Packit |
5ce601 |
ISC's ticketing system is publicly readable; however, you must have an
|
|
Packit |
5ce601 |
account to file a new issue. You can either register locally or use
|
|
Packit |
5ce601 |
credentials from an existing account at GitHub, GitLab, Google, Twitter,
|
|
Packit |
5ce601 |
or Facebook.
|
|
Packit |
5ce601 |
|
|
Packit |
5ce601 |
Reporting possible security issues
|
|
Packit |
5ce601 |
|
|
Packit |
5ce601 |
If you think you may be seeing a potential security vulnerability in BIND
|
|
Packit |
5ce601 |
(for example, a crash with REQUIRE, INSIST, or ASSERT failure), please
|
|
Packit |
5ce601 |
report it immediately by emailing to security-officer@isc.org. Plain-text
|
|
Packit |
5ce601 |
e-mail is not a secure choice for communications concerning undisclosed
|
|
Packit |
5ce601 |
security issues so please encrypt your communications to us if possible,
|
|
Packit |
5ce601 |
using the ISC Security Officer public key.
|
|
Packit |
5ce601 |
|
|
Packit |
5ce601 |
Do not discuss undisclosed security vulnerabilities on any public mailing
|
|
Packit |
5ce601 |
list. ISC has a long history of handling reported vulnerabilities promptly
|
|
Packit |
5ce601 |
and effectively and we respect and acknowledge responsible reporters.
|
|
Packit |
5ce601 |
|
|
Packit |
5ce601 |
ISC's Security Vulnerability Disclosure Policy is documented at https://
|
|
Packit |
5ce601 |
kb.isc.org/article/AA-00861/0.
|
|
Packit |
5ce601 |
|
|
Packit |
5ce601 |
If you have a crash, you may want to consult ?What to do if your BIND or
|
|
Packit |
5ce601 |
DHCP server has crashed.?
|
|
Packit |
5ce601 |
|
|
Packit |
5ce601 |
Contributing code
|
|
Packit |
5ce601 |
|
|
Packit |
5ce601 |
BIND is licensed under the Mozilla Public License 2.0. Earier versions
|
|
Packit |
5ce601 |
(BIND 9.10 and earlier) were licensed under the ISC License
|
|
Packit |
5ce601 |
|
|
Packit |
5ce601 |
ISC does not require an explicit copyright assignment for patch
|
|
Packit |
5ce601 |
contributions. However, by submitting a patch to ISC, you implicitly
|
|
Packit |
5ce601 |
certify that you are the author of the code, that you intend to reliquish
|
|
Packit |
5ce601 |
exclusive copyright, and that you grant permission to publish your work
|
|
Packit |
5ce601 |
under the open source license used for the BIND version(s) to which your
|
|
Packit |
5ce601 |
patch will be applied.
|
|
Packit |
5ce601 |
|
|
Packit |
5ce601 |
BIND code
|
|
Packit |
5ce601 |
|
|
Packit |
5ce601 |
Patches for BIND may be submitted directly via merge requests in ISC's
|
|
Packit |
5ce601 |
Gitlab source repository for BIND.
|
|
Packit |
5ce601 |
|
|
Packit |
5ce601 |
Patches can also be submitted as diffs against a specific version of BIND
|
|
Packit |
5ce601 |
-- preferably the current top of the master branch. Diffs may be generated
|
|
Packit |
5ce601 |
using either git format-patch or git diff.
|
|
Packit |
5ce601 |
|
|
Packit |
5ce601 |
Those wanting to write code for BIND may be interested in the developer
|
|
Packit |
5ce601 |
information page, which includes information about BIND design and coding
|
|
Packit |
5ce601 |
practices, including discussion of internal APIs and overall system
|
|
Packit |
5ce601 |
architecture. (This is a work in progress, and still quite preliminary.)
|
|
Packit |
5ce601 |
|
|
Packit |
5ce601 |
Every patch submitted will be reviewed by ISC engineers following our code
|
|
Packit |
5ce601 |
review process before it is merged.
|
|
Packit |
5ce601 |
|
|
Packit |
5ce601 |
It may take considerable time to review patch submissions, especially if
|
|
Packit |
5ce601 |
they don't meet ISC style and quality guidelines. If a patch is a good
|
|
Packit |
5ce601 |
idea, we can and will do additional work to bring it up to par, but if
|
|
Packit |
5ce601 |
we're busy with other work, it may take us a long time to get to it.
|
|
Packit |
5ce601 |
|
|
Packit |
5ce601 |
To ensure your patch is acted on as promptly as possible, please:
|
|
Packit |
5ce601 |
|
|
Packit |
5ce601 |
* Try to adhere to the BIND 9 coding style.
|
|
Packit |
5ce601 |
* Run make check to ensure your change hasn't caused any functional
|
|
Packit |
5ce601 |
regressions.
|
|
Packit |
5ce601 |
* Document your work, both in the patch itself and in the accompanying
|
|
Packit |
5ce601 |
email.
|
|
Packit |
5ce601 |
* In patches that make non-trivial functional changes, include system
|
|
Packit |
5ce601 |
tests if possible; when introducing or substantially altering a
|
|
Packit |
5ce601 |
library API, include unit tests. See Testing for more information.
|
|
Packit |
5ce601 |
|
|
Packit |
5ce601 |
Changes to configure
|
|
Packit |
5ce601 |
|
|
Packit |
5ce601 |
If you need to make changes to configure, you should not edit it directly;
|
|
Packit |
5ce601 |
instead, edit configure.in, then run autoconf. Similarly, instead of
|
|
Packit |
5ce601 |
editing config.h.in directly, edit configure.in and run autoheader.
|
|
Packit |
5ce601 |
|
|
Packit |
5ce601 |
When submitting a patch as a diff, it's fine to omit the configure diffs
|
|
Packit |
5ce601 |
to save space. Just send the configure.in diffs and we'll generate the new
|
|
Packit |
5ce601 |
configure during the review process.
|
|
Packit |
5ce601 |
|
|
Packit |
5ce601 |
Documentation
|
|
Packit |
5ce601 |
|
|
Packit |
5ce601 |
All functional changes should be documented. There are three types of
|
|
Packit |
5ce601 |
documentation in the BIND source tree:
|
|
Packit |
5ce601 |
|
|
Packit |
5ce601 |
* Man pages are kept alongside the source code for the commands they
|
|
Packit |
5ce601 |
document, in files ending in .docbook; for example, the named man page
|
|
Packit |
5ce601 |
is bin/named/named.docbook.
|
|
Packit |
5ce601 |
* The BIND 9 Administrator Reference Manual is mostly in doc/arm/
|
|
Packit |
5ce601 |
Bv9ARM-book.xml, plus a few other XML files that are included in it.
|
|
Packit |
5ce601 |
* API documentation is in the header file describing the API, in
|
|
Packit |
5ce601 |
Doxygen-formatted comments.
|
|
Packit |
5ce601 |
|
|
Packit |
5ce601 |
It is not necessary to edit any documentation files other than these; all
|
|
Packit |
5ce601 |
PDF, HTML, and nroff-format man page files will be updated automatically
|
|
Packit |
5ce601 |
from the docbook and XML files after merging.
|
|
Packit |
5ce601 |
|
|
Packit |
5ce601 |
Patches to improve existing documentation are also very welcome!
|
|
Packit |
5ce601 |
|
|
Packit |
5ce601 |
Tests
|
|
Packit |
5ce601 |
|
|
Packit |
5ce601 |
BIND is a large and complex project. We rely heavily on continuous
|
|
Packit |
5ce601 |
automated testing and cannot merge new code without adequate test
|
|
Packit |
5ce601 |
coverage. Please see the 'Testing' section of doc/dev/dev.md for more
|
|
Packit |
5ce601 |
information.
|
|
Packit |
5ce601 |
|
|
Packit |
5ce601 |
Thanks
|
|
Packit |
5ce601 |
|
|
Packit |
5ce601 |
Thank you for your interest in contributing to the ongoing development of
|
|
Packit |
5ce601 |
BIND.
|