[thirdparty/pdns.git] / CONTRIBUTING.md

Contributing to PowerDNS
------------------------
Thank you for you interest to contribute to the PowerDNS project. This document
will explain some of the things you need to keep in mind when contributing to
ease the workflow of this.

# Issue Tracker
When you post an issue or feature request to the
[issue tracker](https://github.com/PowerDNS/pdns/issues), make sure this hasn't
been reported before. If there is an open issue, add extra information on this
issue or show that you have the same issue/want this feature by adding a `:+1:`.

If there is no similar issue, feature request or you're not sure, open a new
issue.

## Filing a Feature Request
When filing a feature request, please use the Feature request template provided.

Please be as elaborate as possible when describing the feature you need. Provide
at least the following information (if they are relevant):

* Use case (what is the 'masterplan' that requires this feature)
* Description of what the feature should do

## Filing an Issue or Bug
**Note:** if you're planning to file a security bug, look at our
[Security Policy](https://doc.powerdns.com/md/security/) first.

When filing an issue or bug report, make the title of the issue a very short
summary (e.g. "Recursor crash when some-setting is set to 'crash'"). In the
content of the issue, be as detailed as possible. Supply at least the following
information:

* PowerDNS version
* Where you got the software from (e.g. distribution, compiled yourself)
* Operating System and version
* Steps to reproduce: How can we reproduce the issue
* Expected behavior: what did you expect what would happen?
* Observed behavior: what actually happened when following the steps?
* Relevant logs: Please use code blocks (\`\`\`) to format console output, logs, and code as it's very hard to read otherwise.

We provide convenient templates that make it easy to not forget any of these steps.

If you have already looked deeper into the problem, provide what you found as
well.

# Filing a Pull Request
Code contributions are sent as a pull request on [GitHub](https://github.com/PowerDNS/pdns/pulls).
By submitting a Pull Request you agree to your code becoming GPLv2 licensed.

## Pull Request Guidelines
A pull request, at the least, should have:

* A clear and concise title (not e.g. 'Issue #1234')
* A description of the patch (what issue does it solve or what feature does it add)
* Documentation for the feature or when current behaviour changes
* Regression and/or unit tests

And must:
* Be filed against the master branch before any release branch
* Pass all tests in our CI (currently Github Actions and CircleCI)

Information on the tests can be found in the repository at
[/regression-tests/README.md](https://github.com/PowerDNS/pdns/blob/master/regression-tests/README.md)
,
[/regression-tests.recursor/README.md](https://github.com/PowerDNS/pdns/blob/master/regression-tests.recursor/README.md),
plus various other directories with `regression-tests.*` names.

## Commit Guidelines
* Tell why the change does what it does, not how it does it.
* The first line should be short (preferably less than 50 characters)
* The rest of the commit body should be wrapped at 72 characters (see [this](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html) for more info)
* If this commit fixes an issue, put "Closes #XXXX" in the message
* Do not put whitespace fixes/cleanup and functionality changes in the same commit

# Coding Guidelines
We have `clang-format` in place, but not for all files yet.
This is an incremental process.
If you're adding new code, adhering to the formatting config is appreciated.
Formatting breakage in already formatted files will be caught by the CI.
To format all files that are supposed to be formatted, run `make format-code` in the root of the tree.

Additional guidelines:

* Don't have end-of-line whitespace
* Use spaces instead of tabs
* Although the codebase does not consistently have them, [docblock](https://www.doxygen.nl/manual/docblocks.html)s on functions and classes are appreciated
* Never hesitate to write comments on anything that might not be immediately clear just from reading the code
* When adding whole new things, consider putting them in a `pdns::X` namespace. Look for `namespace pdns` in the codebase for examples.
Commit	Line	Data
11902fff PL	1	Contributing to PowerDNS
	2	------------------------
	3	Thank you for you interest to contribute to the PowerDNS project. This document
	4	will explain some of the things you need to keep in mind when contributing to
	5	ease the workflow of this.
	6
	7	# Issue Tracker
	8	When you post an issue or feature request to the
	9	[issue tracker](https://github.com/PowerDNS/pdns/issues), make sure this hasn't
	10	been reported before. If there is an open issue, add extra information on this
	11	issue or show that you have the same issue/want this feature by adding a `:+1:`.
	12
	13	If there is no similar issue, feature request or you're not sure, open a new
	14	issue.
	15
	16	## Filing a Feature Request
c1fc5d10	17	When filing a feature request, please use the Feature request template provided.
11902fff PL	18
	19	Please be as elaborate as possible when describing the feature you need. Provide
	20	at least the following information (if they are relevant):
	21
	22	* Use case (what is the 'masterplan' that requires this feature)
	23	* Description of what the feature should do
	24
	25	## Filing an Issue or Bug
	26	Note: if you're planning to file a security bug, look at our
	27	[Security Policy](https://doc.powerdns.com/md/security/) first.
	28
	29	When filing an issue or bug report, make the title of the issue a very short
	30	summary (e.g. "Recursor crash when some-setting is set to 'crash'"). In the
	31	content of the issue, be as detailed as possible. Supply at least the following
	32	information:
	33
	34	* PowerDNS version
76d09a54	35	* Where you got the software from (e.g. distribution, compiled yourself)
11902fff PL	36	* Operating System and version
	37	* Steps to reproduce: How can we reproduce the issue
	38	* Expected behavior: what did you expect what would happen?
4821dd69	39	* Observed behavior: what actually happened when following the steps?
11902fff PL	40	* Relevant logs: Please use code blocks (\`\`\`) to format console output, logs, and code as it's very hard to read otherwise.
11902fff PL	41
c1fc5d10 PD	42	We provide convenient templates that make it easy to not forget any of these steps.
c1fc5d10 PD	43
11902fff PL	44	If you have already looked deeper into the problem, provide what you found as
	45	well.
	46
	47	# Filing a Pull Request
	48	Code contributions are sent as a pull request on [GitHub](https://github.com/PowerDNS/pdns/pulls).
c1fc5d10	49	By submitting a Pull Request you agree to your code becoming GPLv2 licensed.
11902fff PL	50
	51	## Pull Request Guidelines
	52	A pull request, at the least, should have:
	53
76d09a54	54	* A clear and concise title (not e.g. 'Issue #1234')
11902fff PL	55	* A description of the patch (what issue does it solve or what feature does it add)
	56	* Documentation for the feature or when current behaviour changes
	57	* Regression and/or unit tests
	58
	59	And must:
	60	* Be filed against the master branch before any release branch
c1fc5d10	61	* Pass all tests in our CI (currently Github Actions and CircleCI)
11902fff	62
f1fe0aa3 PL	63	Information on the tests can be found in the repository at
f1fe0aa3 PL	64	[/regression-tests/README.md](https://github.com/PowerDNS/pdns/blob/master/regression-tests/README.md)
c1fc5d10 PD	65	,
	66	[/regression-tests.recursor/README.md](https://github.com/PowerDNS/pdns/blob/master/regression-tests.recursor/README.md),
	67	plus various other directories with `regression-tests.*` names.
f1fe0aa3	68
11902fff PL	69	## Commit Guidelines
11902fff PL	70	* Tell why the change does what it does, not how it does it.
e2bd355f	71	* The first line should be short (preferably less than 50 characters)
11902fff PL	72	* The rest of the commit body should be wrapped at 72 characters (see [this](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html) for more info)
	73	* If this commit fixes an issue, put "Closes #XXXX" in the message
	74	* Do not put whitespace fixes/cleanup and functionality changes in the same commit
	75
	76	# Coding Guidelines
c1fc5d10 PD	77	We have `clang-format` in place, but not for all files yet.
	78	This is an incremental process.
	79	If you're adding new code, adhering to the formatting config is appreciated.
	80	Formatting breakage in already formatted files will be caught by the CI.
f8b2853a	81	To format all files that are supposed to be formatted, run `make format-code` in the root of the tree.
c1fc5d10 PD	82
c1fc5d10 PD	83	Additional guidelines:
11902fff PL	84
	85	* Don't have end-of-line whitespace
	86	* Use spaces instead of tabs
d8e72253	87	* Although the codebase does not consistently have them, [docblock](https://www.doxygen.nl/manual/docblocks.html)s on functions and classes are appreciated
c1fc5d10	88	* Never hesitate to write comments on anything that might not be immediately clear just from reading the code
b2368658	89	* When adding whole new things, consider putting them in a `pdns::X` namespace. Look for `namespace pdns` in the codebase for examples.