Commit 985d35f6 authored by Evan Hunt's avatar Evan Hunt

Set up CONTRIBUTING.md

- moved into place from doc/dev/contrib.md
- build CONTRIBUTING from CONTRIBUTING.md, like README and OPTIONS
parent f22af098
Pipeline #428 passed with stages
in 11 minutes and 7 seconds
BIND Source Access and Contributor Guidelines
Feb 22, 2018
Contents
1. Access to source code
2. Reporting bugs
3. Contributing code
Introduction
Thank you for using BIND!
BIND is open source software that implements the Domain Name System (DNS)
protocols for the Internet. It is a reference implementation of those
protocols, but it is also production-grade software, suitable for use in
high-volume and high-reliability applications. It is by far the most
widely used DNS software, providing a robust and stable platform on top of
which organizations can build distributed computing systems with the
knowledge that those systems are fully compliant with published DNS
standards.
BIND is and will always remain free and openly available. It can be used
and modified in any way by anyone.
BIND is maintained by the Internet Systems Consortium, a public-benefit
501(c)(3) nonprofit, using a "managed open source" approach: anyone can
see the source, but only ISC employees have commit access. Until recently,
the source could only be seen once ISC had published a release: read
access to the source repository was restricted just as commit access was.
That's now changing, with the opening of a public git mirror to the BIND
source tree (see below).
Access to source code
Public BIND releases are always available from the ISC FTP site.
A public-access GIT repository is also available at https://gitlab.isc.org
. This repository is a mirror, updated several times per day, of the
source repository maintained by ISC. It contains all the public release
branches; upcoming releases can be viewed in their current state at any
time. It does not contain development branches or unreviewed work in
progress. Commits which address security vulnerablilities are withheld
until after public disclosure.
You can browse the source online via https://gitlab.isc.org/isc-projects/
bind9
To clone the repository, use:
$ git clone https://gitlab.isc.org/isc-projects/bind9.git
Release branch names are of the form v9_X, where X represents the second
number in the BIND 9 version number. So, to check out the BIND 9.12
branch, use:
$ git checkout v9_12
Whenever a branch is ready for publication, a tag will be placed of the
form v9_X_Y. The 9.12.0 release, for instance, is tagged as v9_12_0.
The branch in which the next major release is being developed is called
master.
Reporting bugs
Reports of flaws in the BIND package, including software bugs, errors in
the documentation, missing files in the tarball, suggested changes or
requests for new features, etc, can be filed using https://gitlab.isc.org/
isc-projects/bind9/issues.
Due to a large ticket backlog, we are sometimes slow to respond,
especially if a bug is cosmetic or if a feature request is vague or low in
priority, but we will try at least to acknowledge legitimate bug reports
within a week.
ISC's ticketing system is publicly readable; however, you must have an
account to file a new issue. You can either register locally or use
credentials from an existing account at GitHub, GitLab, Google, Twitter,
or Facebook.
Reporting possible security issues
If you think you may be seeing a potential security vulnerability in BIND
(for example, a crash with REQUIRE, INSIST, or ASSERT failure), please
report it immediately by emailing to security-officer@isc.org. Plain-text
e-mail is not a secure choice for communications concerning undisclosed
security issues so please encrypt your communications to us if possible,
using the ISC Security Officer public key.
Do not discuss undisclosed security vulnerabilites on any public mailing
list. ISC has a long history of handling reported vulnerabilities promptly
and effectively and we respect and acknowledge responsible reporters.
ISC's Security Vulnerability Disclosure Policy is documented at https://
kb.isc.org/article/AA-00861/0.
If you have a crash, you may want to consult ?What to do if your BIND or
DHCP server has crashed.?
Contributing code
BIND is licensed under the Mozilla Public License 2.0. Earier versions
(BIND 9.10 and earlier) were licensed under the ISC License
ISC does not require an explicit copyright assignment for patch
contributions. However, by submitting a patch to ISC, you implicitly
certify that you are the author of the code, that you intend to reliquish
exclusive copyright, and that you grant permission to publish your work
under the open source license used for the BIND version(s) to which your
patch will be applied.
BIND code
Patches for BIND may be submitted directly via merge requests in ISC's
Gitlab source repository for BIND.
Patches can also be submitted as diffs against a specific version of BIND
-- preferably the current top of the master branch. Diffs may be generated
using either git format-patch or git diff.
Those wanting to write code for BIND may be interested in the developer
information page, which includes information about BIND design and coding
practices, including discussion of internal APIs and overall system
architecture. (This is a work in progress, and still quite preliminary.)
Every patch submitted will be reviewed by ISC engineers following our code
review process before it is merged.
It may take considerable time to review patch submissions, especially if
they don't meet ISC style and quality guidelines. If a patch is a good
idea, we can and will do additional work to bring it up to par, but if
we're busy with other work, it may take us a long time to get to it.
To ensure your patch is acted on as promptly as possible, please:
* Try to adhere to the BIND 9 coding style.
* Run make check to ensure your change hasn't caused any functional
regressions.
* Document your work, both in the patch itself and in the accompanying
email.
* In patches that make non-trivial functional changes, include system
tests if possible; when introducing or substantially altering a
library API, include unit tests. See Testing for more information.
Changes to configure
If you need to make changes to configure, you should not edit it directly;
instead, edit configure.in, then run autoconf. Similarly, instead of
editing config.h.in directly, edit configure.in and run autoheader.
When submitting a patch as a diff, it's fine to omit the configure diffs
to save space. Just send the configure.in diffs and we'll generate the new
configure during the review process.
Documentation
All functional changes should be documented. There are three types of
documentation in the BIND source tree:
* Man pages are kept alongside the source code for the commands they
document, in files ending in .docbook; for example, the named man page
is bin/named/named.docbook.
* The BIND 9 Administrator Reference Manual is mostly in doc/arm/
Bv9ARM-book.xml, plus a few other XML files that are included in it.
* API documentation is in the header file describing the API, in
Doxygen-formatted comments.
It is not necessary to edit any documentation files other than these; all
PDF, HTML, and nroff-format man page files will be updated automatically
from the docbook and XML files after merging.
Patches to improve existing documentation are also very welcome!
Tests
BIND is a large and complex project. We rely heavily on continuous
automated testing and cannot merge new code without adequate test
coverage. Please see the 'Testing' section of doc/dev/dev.md for more
information.
Thanks
Thank you for your interest in contributing to the ongoing development of
BIND.
<!-- <!--
- Copyright (C) Internet Systems Consortium, Inc. ("ISC") - Copyright (C) 2017 Internet Systems Consortium, Inc. ("ISC")
- -
- This Source Code Form is subject to the terms of the Mozilla Public - This Source Code Form is subject to the terms of the Mozilla Public
- License, v. 2.0. If a copy of the MPL was not distributed with this - License, v. 2.0. If a copy of the MPL was not distributed with this
- file, You can obtain one at http://mozilla.org/MPL/2.0/. - file, You can obtain one at http://mozilla.org/MPL/2.0/.
-
- See the COPYRIGHT file distributed with this work for additional
- information regarding copyright ownership.
--> -->
## BIND Source Access and Contributor Guidelines ## BIND Source Access and Contributor Guidelines
*Apr 14, 2017* *Feb 22, 2018*
### Contents ### Contents
...@@ -47,7 +44,7 @@ Public BIND releases are always available from the ...@@ -47,7 +44,7 @@ Public BIND releases are always available from the
[ISC FTP site](ftp://ftp.isc.org/isc/bind9). [ISC FTP site](ftp://ftp.isc.org/isc/bind9).
A public-access GIT repository is also available at A public-access GIT repository is also available at
[https://bindmember.isc.org](https://bindmember.isc.org). [https://gitlab.isc.org](https://gitlab.isc.org).
This repository is a mirror, updated several times per day, of the This repository is a mirror, updated several times per day, of the
source repository maintained by ISC. It contains all the public release source repository maintained by ISC. It contains all the public release
branches; upcoming releases can be viewed in their current state at any branches; upcoming releases can be viewed in their current state at any
...@@ -56,104 +53,105 @@ progress. Commits which address security vulnerablilities are withheld ...@@ -56,104 +53,105 @@ progress. Commits which address security vulnerablilities are withheld
until after public disclosure. until after public disclosure.
You can browse the source online via You can browse the source online via
[https://bindmember.isc.org/cgi-bin/gitweb.cgi?p=bind9.git;a=summary](https://bindmember.isc.org/cgi-bin/gitweb.cgi?p=bind9.git;a=summary) [https://gitlab.isc.org/isc-projects/bind9](https://gitlab.isc.org/isc-projects/bind9)
To clone the repository, use: To clone the repository, use:
> $ git clone https://bindmember.isc.org/git/bind9.git > $ git clone https://gitlab.isc.org/isc-projects/bind9.git
Branch names are of the form `v9_X`, where X represents the second number in the BIND 9 version number. So, to check out the BIND 9.10 branch, use: Release branch names are of the form `v9_X`, where X represents the second
number in the BIND 9 version number. So, to check out the BIND 9.12
branch, use:
> $ git checkout v9_10 > $ git checkout v9_12
Whenever a branch is ready for publication, a tag will be placed of the Whenever a branch is ready for publication, a tag will be placed of the
form `v9_X_Y`. The 9.9.5 release, for instance, is tagged as `v9_9_5`. form `v9_X_Y`. The 9.12.0 release, for instance, is tagged as `v9_12_0`.
The branch in which the next major release is being developed is called The branch in which the next major release is being developed is called
`master`. `master`.
### <a name="bugs"></a>Reporting bugs ### <a name="bugs"></a>Reporting bugs
Reports of flaws in the BIND package, including software bugs, errors in Reports of flaws in the BIND package, including software bugs, errors
the documentation, missing files in the tarball, etc, can be emailed to in the documentation, missing files in the tarball, suggested changes
`bind9-bugs@isc.org`, or reported via the or requests for new features, etc, can be filed using
[bug submission form](http://www.isc.org/community/report-bug) at [https://gitlab.isc.org/isc-projects/bind9/issues](https://gitlab.isc.org/isc-projects/bind9/issues).
[http://www.isc.org/community/report-bug](http://www.isc.org/community/report-bug).
Suggested changes or requests for new features can be emailed to
`bind-suggest@isc.org`. Both bugs and suggestions are stored in the
ticketing system used by the software engineering team at ISC.
All submissions to the ticketing system receive an automatic response. Any Due to a large ticket backlog, we are sometimes slow to respond,
followup email sent to the ticketing system should use the same subject especially if a bug is cosmetic or if a feature request is vague or
header, so that it will be routed to the same ticket. low in priority, but we will try at least to acknowledge legitimate
bug reports within a week.
Due to a large ticket backlog and an even larger quantity of incoming spam, ISC's ticketing system is publicly readable; however, you must have
we are sometimes slow to respond, especially if a bug is cosmetic or if a an account to file a new issue. You can either register locally or
feature request is vague or low in priority, but we will try at least to use credentials from an existing account at GitHub, GitLab, Google,
acknowledge legitimate bug reports within a week. Twitter, or Facebook.
Currently, ISC's ticketing system is not publicly readable. However, ISC ### Reporting possible security issues
may open it in the future. Please do not include information you consider If you think you may be seeing a potential security vulnerability in BIND
to be confidential. (for example, a crash with REQUIRE, INSIST, or ASSERT failure), please
report it immediately by emailing to security-officer@isc.org. Plain-text
e-mail is not a secure choice for communications concerning undisclosed
security issues so please encrypt your communications to us if possible,
using the [ISC Security Officer public key](https://www.isc.org/downloads/software-support-policy/openpgp-key/).
### <a name="bugs"></a>Contributing code Do not discuss undisclosed security vulnerabilites on any public mailing list.
ISC has a long history of handling reported vulnerabilities promptly and
effectively and we respect and acknowledge responsible reporters.
BIND's [open source ISC's Security Vulnerability Disclosure Policy is documented at [https://kb.isc.org/article/AA-00861/0](https://kb.isc.org/article/AA-00861/0).
license](http://www.isc.org/downloads/software-support-policy/isc-license/)
not require changes to be contributed back to ISC, but this page
includes some guidelines for those who would like to do so.
We accept two different types of code contribution: Code intended for If you have a crash, you may want to consult
inclusion in [BIND](#bind) itself, and code intended for the [‘What to do if your BIND or DHCP server has crashed.’](https://kb.isc.org/article/AA-00340/89/What-to-do-if-your-BIND-or-DHCP-server-has-crashed.html)
[`contrib`](#contrib) directory.
#### <a name="bind"></a>BIND code ### <a name="bugs"></a>Contributing code
Patches for BIND itself may be submitted using the same methods as bug BIND is licensed under the
reports or suggestions. When submitting a patch, please prepend the [Mozilla Public License 2.0](http://www.isc.org/downloads/software-support-policy/isc-license/).
subject header with "`[PATCH]`" so it will be easier for us to find. If Earier versions (BIND 9.10 and earlier) were licensed under the [ISC License](http://www.isc.org/downloads/software-support-policy/isc-license/)
your patch introduces a new feature in BIND, please submit it to
`bind-suggest@isc.org`; if it fixes a bug, please submit it to
`bind9-bugs@isc.org`.
ISC does not require an explicit copyright assignment for patch ISC does not require an explicit copyright assignment for patch
contributions. However, by submitting a patch to ISC, you implicitly contributions. However, by submitting a patch to ISC, you implicitly
certify that you are the author of the code, that you intend to reliquish certify that you are the author of the code, that you intend to reliquish
exclusive copyright, and that you grant permission to publish your work exclusive copyright, and that you grant permission to publish your work
under the under the open source license used for the BIND version(s) to which your
[Mozilla Public License 2.0](http://www.isc.org/downloads/software-support-policy/isc-license/) patch will be applied.
for BIND 9.11 and higher, and the
[ISC License](http://www.isc.org/downloads/software-support-policy/isc-license/)
for BIND 9.10 and earlier.
Patches should be submitted as diffs against a specific version of BIND -- #### <a name="bind"></a>BIND code
preferably the current top of the `master` branch. Diffs may be
generated using either `git format-patch` or `git diff`. Patches for BIND may be submitted directly via merge requests in
[ISC's Gitlab](https://gitlab.isc.org/isc-projects/bind9/) source
repository for BIND.
Those wanting to write code for BIND may be interested in the [developer Patches can also be submitted as diffs against a specific version of
information](dev.md) page, which includes information about BIND design and BIND -- preferably the current top of the `master` branch. Diffs may
coding practices, including discussion of internal APIs and overall system be generated using either `git format-patch` or `git diff`.
architecture. (This is a work in progress, and still quite preliminary.)
Every patch submitted will be reviewed by ISC engineers following our [code Those wanting to write code for BIND may be interested in the
review process](dev.md#reviews) before it is merged. [developer information](doc/dev/dev.md) page, which includes information
about BIND design and coding practices, including discussion of internal
APIs and overall system architecture. (This is a work in progress, and
still quite preliminary.)
Every patch submitted will be reviewed by ISC engineers following our
[code review process](doc/dev/dev.md#reviews) before it is merged.
It may take considerable time to review patch submissions, especially if It may take considerable time to review patch submissions, especially if
they don't meet ISC style and quality guidelines. If the patch is a good they don't meet ISC style and quality guidelines. If a patch is a good
idea, we can and will do additional work to bring them up to par, but if idea, we can and will do additional work to bring it up to par, but if
we're busy with other work, it may take us a long time to get to it. we're busy with other work, it may take us a long time to get to it.
To ensure your patch is acted on as promptly as possible, please: To ensure your patch is acted on as promptly as possible, please:
* Try to adhere to the [BIND 9 coding style](style.md). * Try to adhere to the [BIND 9 coding style](doc/dev/style.md).
* Run `make` `check` to ensure your change hasn't caused any * Run `make` `check` to ensure your change hasn't caused any
functional regressions. functional regressions.
* Document your work, both in the patch itself and in the * Document your work, both in the patch itself and in the
accompanying email. accompanying email.
* In patches that make non-trivial functional changes, include system * In patches that make non-trivial functional changes, include system
tests if possible; when introducing or substantially altering a tests if possible; when introducing or substantially altering a
library API, include unit tests. See [Testing](dev.md#testing) library API, include unit tests. See [Testing](doc/dev/dev.md#testing)
for more information. for more information.
##### Changes to `configure` ##### Changes to `configure`
...@@ -163,9 +161,9 @@ directly; instead, edit `configure.in`, then run `autoconf`. Similarly, ...@@ -163,9 +161,9 @@ directly; instead, edit `configure.in`, then run `autoconf`. Similarly,
instead of editing `config.h.in` directly, edit `configure.in` and run instead of editing `config.h.in` directly, edit `configure.in` and run
`autoheader`. `autoheader`.
When submitting your patch, it is fine to omit the `configure` diffs. When submitting a patch as a diff, it's fine to omit the `configure`
Just send the `configure.in` diffs and we'll generate the new `configure` diffs to save space. Just send the `configure.in` diffs and we'll
during the review process. generate the new `configure` during the review process.
##### Documentation ##### Documentation
...@@ -181,24 +179,20 @@ of documentation in the BIND source tree: ...@@ -181,24 +179,20 @@ of documentation in the BIND source tree:
* API documentation is in the header file describing the API, in * API documentation is in the header file describing the API, in
Doxygen-formatted comments. Doxygen-formatted comments.
It is not necessary to edit any documentation files other than these; the It is not necessary to edit any documentation files other than these;
PDF, HTML, and `nroff`-format files will be generated automatically all PDF, HTML, and `nroff`-format man page files will be updated
from the `docbook` and `XML` files by a script whenever a documentation automatically from the `docbook` and `XML` files after merging.
change is merged to a release branch.
Patches to improve existing documentation are also very welcome!
#### <a name="contrib"></a>Contrib code ##### Tests
The software in the `contrib` directory of the BIND 9 `tar` archive is not BIND is a large and complex project. We rely heavily on continuous
formally supported by ISC, but is included for the convenience of users. automated testing and cannot merge new code without adequate test coverage.
These are things we consider useful or informative, but are not able to Please see [the 'Testing' section of doc/dev/dev.md](doc/dev/dev.md#testing)
support at the same level as BIND. for more information.
`contrib` includes some useful DNS-related open source tools such as `zkt`, #### Thanks
`nslint`, and the `idnkit` library for internationalized domain name
support; useful scripts such as `nanny.pl` and `mkdane.sh`; performance
testers including `queryperf` and `perftcpdns`; and drivers and modules for
DLZ.
If you have code with a BSD-compatible license that you would like us to Thank you for your interest in contributing to the ongoing development
include in `contrib`, please send it to `bind-suggest@isc.org`, with of BIND.
"`[CONTRIB]`" in the subject header.
...@@ -22,7 +22,7 @@ MANPAGES = isc-config.sh.1 ...@@ -22,7 +22,7 @@ MANPAGES = isc-config.sh.1
HTMLPAGES = isc-config.sh.html HTMLPAGES = isc-config.sh.html
MANOBJS = README HISTORY OPTIONS ${MANPAGES} ${HTMLPAGES} MANOBJS = README HISTORY OPTIONS CONTRIBUTING ${MANPAGES} ${HTMLPAGES}
@BIND9_MAKE_RULES@ @BIND9_MAKE_RULES@
...@@ -106,6 +106,10 @@ OPTIONS: OPTIONS.md ...@@ -106,6 +106,10 @@ OPTIONS: OPTIONS.md
${PANDOC} --email-obfuscation=none -s -t html OPTIONS.md | \ ${PANDOC} --email-obfuscation=none -s -t html OPTIONS.md | \
${W3M} -dump -cols 75 -O ascii -T text/html > $@ ${W3M} -dump -cols 75 -O ascii -T text/html > $@
CONTRIBUTING: CONTRIBUTING.md
${PANDOC} --email-obfuscation=none -s -t html CONTRIBUTING.md | \
${W3M} -dump -cols 75 -O ascii -T text/html > $@
unit:: unit::
sh ${top_builddir}/unit/unittest.sh sh ${top_builddir}/unit/unittest.sh
......
...@@ -80,8 +80,8 @@ ISC maintains a public git repository for BIND; details can be found at ...@@ -80,8 +80,8 @@ ISC maintains a public git repository for BIND; details can be found at
http://www.isc.org/git/. http://www.isc.org/git/.
Information for BIND contributors can be found in the following files: - Information for BIND contributors can be found in the following files: -
General information: doc/dev/contrib.md - BIND 9 code style: doc/dev/ General information: CONTRIBUTING.md - BIND 9 code style: doc/dev/style.md
style.md - BIND architecture and developer guide: doc/dev/dev.md - BIND architecture and developer guide: doc/dev/dev.md
Patches for BIND may be submitted either as Github pull requests or via Patches for BIND may be submitted either as Github pull requests or via
email. When submitting a patch via email, please prepend the subject email. When submitting a patch via email, please prepend the subject
......
...@@ -93,7 +93,7 @@ ISC maintains a public git repository for BIND; details can be found ...@@ -93,7 +93,7 @@ ISC maintains a public git repository for BIND; details can be found
at [http://www.isc.org/git/](http://www.isc.org/git/). at [http://www.isc.org/git/](http://www.isc.org/git/).
Information for BIND contributors can be found in the following files: Information for BIND contributors can be found in the following files:
- General information: [doc/dev/contrib.md](doc/dev/contrib.md) - General information: [CONTRIBUTING.md](CONTRIBUTING)
- BIND 9 code style: [doc/dev/style.md](doc/dev/style.md) - BIND 9 code style: [doc/dev/style.md](doc/dev/style.md)
- BIND architecture and developer guide: [doc/dev/dev.md](doc/dev/dev.md) - BIND architecture and developer guide: [doc/dev/dev.md](doc/dev/dev.md)
......
...@@ -3,6 +3,8 @@ ...@@ -3,6 +3,8 @@
./.gitlab-ci.yml X 2018 ./.gitlab-ci.yml X 2018
./Atffile X 2011,2018 ./Atffile X 2011,2018
./CHANGES X 2000,2001,2002,2003,2004,2005,2006,2007,2008,2009,2010,2011,2012,2013,2014,2015,2016,2017,2018 ./CHANGES X 2000,2001,2002,2003,2004,2005,2006,2007,2008,2009,2010,2011,2012,2013,2014,2015,2016,2017,2018
./CONTRIBUTING X 2017,2018
./CONTRIBUTING.md MKD 2017,2018
./COPYRIGHT X 1996,1997,1998,1999,2000,2001,2002,2003,2004,2005,2006,2007,2008,2009,2010,2011,2012,2013,2014,2015,2016,2017,2018 ./COPYRIGHT X 1996,1997,1998,1999,2000,2001,2002,2003,2004,2005,2006,2007,2008,2009,2010,2011,2012,2013,2014,2015,2016,2017,2018
./HISTORY X 2010,2013,2016,2017,2018 ./HISTORY X 2010,2013,2016,2017,2018
./HISTORY.md MKD 2017,2018 ./HISTORY.md MKD 2017,2018
...@@ -3209,7 +3211,6 @@ ...@@ -3209,7 +3211,6 @@
./doc/dev/HOW-ADB-WORKS.txt TXT.BRIEF 2003,2004,2016,2018 ./doc/dev/HOW-ADB-WORKS.txt TXT.BRIEF 2003,2004,2016,2018
./doc/dev/autoconf TXT.BRIEF 2001,2002,2004,2016,2018 ./doc/dev/autoconf TXT.BRIEF 2001,2002,2004,2016,2018
./doc/dev/coding.html HTML 1999,2000,2001,2002,2004,2007,2016,2018 ./doc/dev/coding.html HTML 1999,2000,2001,2002,2004,2007,2016,2018
./doc/dev/contrib.md MKD 2017,2018
./doc/dev/cvs-usage TXT.BRIEF 2000,2001,2004,2016,2018 ./doc/dev/cvs-usage TXT.BRIEF 2000,2001,2004,2016,2018
./doc/dev/dev.md MKD 2017,2018 ./doc/dev/dev.md MKD 2017,2018
./doc/dev/magic_numbers TXT.BRIEF 1999,2000,2001,2002,2004,2016,2018 ./doc/dev/magic_numbers TXT.BRIEF 1999,2000,2001,2002,2004,2016,2018
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment