CONTRIBUTING.md 8.65 KB
Newer Older
Evan Hunt's avatar
Evan Hunt committed
1
<!--
Evan Hunt's avatar
Evan Hunt committed
2
 - Copyright (C) Internet Systems Consortium, Inc. ("ISC")
Evan Hunt's avatar
Evan Hunt committed
3 4 5 6
 -
 - 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
 - file, You can obtain one at http://mozilla.org/MPL/2.0/.
Evan Hunt's avatar
Evan Hunt committed
7 8 9
 -
 - See the COPYRIGHT file distributed with this work for additional
 - information regarding copyright ownership.
Evan Hunt's avatar
Evan Hunt committed
10
-->
11 12
## BIND 9 Source Access and Contributor Guidelines
*May 28, 2020*
Evan Hunt's avatar
Evan Hunt committed
13 14 15 16 17 18 19 20 21

### Contents

1. [Access to source code](#access)
1. [Reporting bugs](#bugs)
1. [Contributing code](#contrib)

### Introduction

22
Thank you for using BIND 9!
Evan Hunt's avatar
Evan Hunt committed
23 24 25 26

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
27
high-volume and high-reliability applications.  It is very
Evan Hunt's avatar
Evan Hunt committed
28 29 30 31 32 33 34 35
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.

36
BIND is maintained by [Internet Systems Consortium](https://www.isc.org),
Evan Hunt's avatar
Evan Hunt committed
37 38
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.
39 40 41
In the past, 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 has changed, as ISC now provides a
Evan Hunt's avatar
Evan Hunt committed
42 43
public git mirror to the BIND source tree (see below).

44 45
At ISC, we're committed to
building communities that are welcoming and inclusive: environments where people
46
are encouraged to share ideas, treat each other with respect, and collaborate
47 48 49
towards the best solutions. To reinforce our commitment, ISC
has adopted a slightly modified version of the Django
[Code of Conduct](https://gitlab.isc.org/isc-projects/bind9/-/blob/master/CODE_OF_CONDUCT.md) for the BIND 9 project, as well as for the conduct of our
50 51
developers throughout the industry.

Evan Hunt's avatar
Evan Hunt committed
52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78
### <a name="access"></a>Access to source code

Public BIND releases are always available from the
[ISC FTP site](ftp://ftp.isc.org/isc/bind9).

A public-access GIT repository is also available at
[https://gitlab.isc.org](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](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

79
Whenever a branch is ready for publication, a tag is placed of the
Evan Hunt's avatar
Evan Hunt committed
80 81 82 83 84 85 86 87 88
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`.

### <a name="bugs"></a>Reporting bugs

Reports of flaws in the BIND package, including software bugs, errors
in the documentation, missing files in the tarball, suggested changes
89
or requests for new features, etc., can be filed using
Evan Hunt's avatar
Evan Hunt committed
90 91 92 93
[https://gitlab.isc.org/isc-projects/bind9/issues](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
94
low in priority, but we try at least to acknowledge legitimate
Evan Hunt's avatar
Evan Hunt committed
95 96
bug reports within a week.

97 98
ISC's GitLab system is publicly readable; however, you must have
an account to create a new issue. You can either register locally or
Evan Hunt's avatar
Evan Hunt committed
99 100 101 102 103 104 105 106 107
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,
108
using the [ISC Security Officer public key](https://www.isc.org/pgpkey/).
Evan Hunt's avatar
Evan Hunt committed
109

110
Do not discuss undisclosed security vulnerabilities on any public mailing list.
Evan Hunt's avatar
Evan Hunt committed
111 112 113
ISC has a long history of handling reported vulnerabilities promptly and
effectively and we respect and acknowledge responsible reporters.

114
ISC's Security Vulnerability Disclosure Policy is documented at [https://kb.isc.org/docs/aa-00861](https://kb.isc.org/docs/aa-00861).
Evan Hunt's avatar
Evan Hunt committed
115 116

If you have a crash, you may want to consult
117
["What to do if your BIND or DHCP server has crashed."](https://kb.isc.org/docs/aa-00340)
Evan Hunt's avatar
Evan Hunt committed
118

119
### <a name="contrib"></a>Contributing code
Evan Hunt's avatar
Evan Hunt committed
120 121

BIND is licensed under the
122 123
[Mozilla Public License 2.0](https://www.mozilla.org/en-US/MPL/2.0/).
Earlier versions (BIND 9.10 and earlier) were licensed under the [ISC License](https://www.isc.org/licenses/)
Evan Hunt's avatar
Evan Hunt committed
124 125 126

ISC does not require an explicit copyright assignment for patch
contributions.  However, by submitting a patch to ISC, you implicitly
127
certify that you are the author of the code, that you intend to relinquish
Evan Hunt's avatar
Evan Hunt committed
128 129 130 131 132 133 134
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.

#### <a name="bind"></a>BIND code

Patches for BIND may be submitted directly via merge requests in
135
[ISC's GitLab](https://gitlab.isc.org/isc-projects/bind9/) source
Evan Hunt's avatar
Evan Hunt committed
136 137 138 139 140 141 142 143 144
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](doc/dev/dev.md) page, which includes information
about BIND design and coding practices, including discussion of internal
145
APIs and overall system architecture.
Evan Hunt's avatar
Evan Hunt committed
146

147
Every patch submitted is reviewed by ISC engineers following our
Evan Hunt's avatar
Evan Hunt committed
148 149 150 151 152 153 154 155 156 157
[code review process](doc/dev/dev.md#reviews) 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](doc/dev/style.md).
158
* Run `make check` to ensure your change hasn't caused any
Evan Hunt's avatar
Evan Hunt committed
159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183
  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](doc/dev/dev.md#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
184 185 186 187
  they document, in files ending in `.rst`: for example, the
  `named` man page is `bin/named/named.rst`.
* The *BIND 9 Administrator Reference Manual* is in the .rst files in
  `doc/arm/`; the PDF and HTML versions are automatically generated from the `.rst` files.
Evan Hunt's avatar
Evan Hunt committed
188 189 190 191 192 193 194 195 196
* API documentation is in the header file describing the API, in
  Doxygen-formatted comments.

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.
197
Please see [the "Testing" section of doc/dev/dev.md](doc/dev/dev.md#testing)
Evan Hunt's avatar
Evan Hunt committed
198 199 200 201 202
for more information.

#### Thanks

Thank you for your interest in contributing to the ongoing development
203
of BIND 9.