CONTRIBUTING.md 8.56 KB
Newer Older
Evan Hunt's avatar
Evan Hunt committed
1
<!--
2
3
4
5
6
7
8
9
10
11
Copyright (C) Internet Systems Consortium, Inc. ("ISC")

SPDX-License-Identifier: MPL-2.0

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 https://mozilla.org/MPL/2.0/.

See the COPYRIGHT file distributed with this work for additional
information regarding copyright ownership.
Evan Hunt's avatar
Evan Hunt committed
12
-->
13
14
## BIND 9 Source Access and Contributor Guidelines
*May 28, 2020*
Evan Hunt's avatar
Evan Hunt committed
15
16
17
18
19
20
21
22
23

### Contents

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

### Introduction

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

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

38
BIND is maintained by [Internet Systems Consortium](https://www.isc.org),
Evan Hunt's avatar
Evan Hunt committed
39
40
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.
41
42
43
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
44
public git repository of the BIND source tree (see below).
Evan Hunt's avatar
Evan Hunt committed
45

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

Evan Hunt's avatar
Evan Hunt committed
55
56
57
58
59
### <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).

60
61
62
63
64
65
A public-access git repository is also available at
[https://gitlab.isc.org](https://gitlab.isc.org).  This repository
contains all public release branches. Upcoming releases can be viewed in
their current state at any time.  Short-lived development branches
contain unreviewed work in progress.  Commits which address security
vulnerablilities are withheld until after public disclosure.
Evan Hunt's avatar
Evan Hunt committed
66
67
68
69
70
71
72
73
74
75
76
77
78
79

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

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

### <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
90
or requests for new features, etc., can be filed using
Evan Hunt's avatar
Evan Hunt committed
91
92
93
94
[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
95
low in priority, but we try at least to acknowledge legitimate
Evan Hunt's avatar
Evan Hunt committed
96
97
bug reports within a week.

98
99
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
100
101
102
103
use credentials from an existing account at GitHub, GitLab, Google,
Twitter, or Facebook.

### Reporting possible security issues
104

Evan Hunt's avatar
Evan Hunt committed
105
106
107
108
109
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,
110
using the [ISC Security Officer public key](https://www.isc.org/pgpkey/).
Evan Hunt's avatar
Evan Hunt committed
111

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

116
117
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
118
119

If you have a crash, you may want to consult
120
["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
121

122
### <a name="contrib"></a>Contributing code
Evan Hunt's avatar
Evan Hunt committed
123
124

BIND is licensed under the
125
[Mozilla Public License 2.0](https://www.mozilla.org/en-US/MPL/2.0/).
126
127
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
128
129
130

ISC does not require an explicit copyright assignment for patch
contributions.  However, by submitting a patch to ISC, you implicitly
131
certify that you are the author of the code, that you intend to relinquish
Evan Hunt's avatar
Evan Hunt committed
132
133
134
135
136
137
138
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
139
[ISC's GitLab](https://gitlab.isc.org/isc-projects/bind9/) source
Evan Hunt's avatar
Evan Hunt committed
140
141
142
repository for BIND.

Patches can also be submitted as diffs against a specific version of
143
BIND -- preferably the current top of the `main` branch.  Diffs may
Evan Hunt's avatar
Evan Hunt committed
144
145
146
147
148
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
149
APIs and overall system architecture.
Evan Hunt's avatar
Evan Hunt committed
150

151
Every patch submitted is reviewed by ISC engineers following our
Evan Hunt's avatar
Evan Hunt committed
152
153
154
155
156
157
158
159
160
161
[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).
162
* Run `make check` to ensure your change hasn't caused any
Evan Hunt's avatar
Evan Hunt committed
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
  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
188
189
190
  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
191
192
  `doc/arm/`; the PDF and HTML versions are automatically generated from
  the `.rst` files.
Evan Hunt's avatar
Evan Hunt committed
193
194
195
196
197
198
199
200
201
* 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.
202
Please see [the "Testing" section of doc/dev/dev.md](doc/dev/dev.md#testing)
Evan Hunt's avatar
Evan Hunt committed
203
204
205
206
207
for more information.

#### Thanks

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