Arturo: /* See also */ add link to patchwork

2019-07-14T13:09:07Z

Arturo: bold sentence about git and linux coding style

2019-07-14T13:07:16Z

bold sentence about git and linux coding style

← Older revision		Revision as of 13:07, 14 July 2019
Line 10:		Line 10:
	That's why we have some rules we would like to highlight.		That's why we have some rules we would like to highlight.

	And in a nutshell, we use git and we follow Linux Kernel patch submission process and coding style.		And in a nutshell, '''we use git and we follow Linux Kernel patch submission process and coding style'''.

	= Rules =		= Rules =

Arturo: refresh page with interlinks etc

2019-07-14T12:57:29Z

refresh page with interlinks etc

← Older revision		Revision as of 12:57, 14 July 2019
Line 24:		Line 24:
	# Include documentation updates within the patch-series.		# Include documentation updates within the patch-series.
	# Include test-suites updates within the patch-series.		# Include test-suites updates within the patch-series.
	# If you have doubts about formatting a patch, look at others commit/patches. There are plenty of examples. If you still have doubts, ask in the ~~[[Mailing lists \|~~ mailing list]]. But ask after doing your homework, i.e. trying yourself.		# If you have doubts about formatting a patch, look at others commit/patches. There are plenty of examples. If you still have doubts, ask in the mailing list. But ask after doing your homework, i.e. trying yourself.
	# Use an email address which is reachable for replies, i.e. don't submit patches from ''root@myserver.example.com''.		# Use an email address which is reachable for replies, i.e. don't submit patches from ''root@myserver.example.com''.
	# Be patient after submitting a patch. Don't expect same day replies. Ping after a week or so.		# Be patient after submitting a patch. Don't expect same day replies. Ping after a week or so.
Line 226:		Line 226:
	Please, read this useful information:		Please, read this useful information:

	* [[Bug reporting]]		* [[Portal:DeveloperDocs/Bug_reporting \| Bug reporting]]
	* [https://git-scm.com/ Git main website]		* [https://git-scm.com/ Git main website]
	* [https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/Documentation/process/coding-style.rst Linux Kernel docs - coding style]		* [https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/Documentation/process/coding-style.rst Linux Kernel docs - coding style]
	* [https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/Documentation/process/submitting-patches.rst Linux Kernel docs - submitting patches]		* [https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/Documentation/process/submitting-patches.rst Linux Kernel docs - submitting patches]
	* [[Development environment]]		* [[Portal:DeveloperDocs/Development_environment \| Development environment]]
	* [[Contributing]]		* [[Portal:DeveloperDocs/Contributing \| Contributing]]
	* [[Mailing lists]]
	* [[Licensing]]

Arturo: create page

2019-07-14T12:25:04Z

create page

New page

Submitting patches is one of the main ways to contributing to the Netfilter project.
We try to follow common patterns in order to put some order in our work.

Sometimes reviewing patches and maintaining software written collaboratively can be difficult.
We would like to keep the review process simple. Also, maintainers needs to understand what your change is about.
In some cases, in the future, the patch may be reverted or reworked. Or simply, someone would need to understand it out of context.
Take into account that there are people following the development only by reading commit messages and not the code itself.
This is the reason that commit messages should be accurate.

That's why we have some rules we would like to highlight.

And in a nutshell, we use git and we follow Linux Kernel patch submission process and coding style.

= Rules =

Please, stick to these rules:

# Every patch should be well formatted (see '''Commit style''' below).
# Don't submit untested patches. You should test your patches and prove they work before sending them out. If you are sharing just an idea, untested, state that clearly in the commit message.
# Put related patches in a patch series. This way maintainers know that they all go together.
# Don't patch-bomb, i.e. don't submit 50 patches in a row. Split patch series in small chunks if possible.
# Use one commit/patch for each logical change. Don't mix different things in the same patch. This eases the review process.
# The repository should be keep consistent between commits, i.e. try to don't introduce changes that breaks the code for no reason.
# Include documentation updates within the patch-series.
# Include test-suites updates within the patch-series.
# If you have doubts about formatting a patch, look at others commit/patches. There are plenty of examples. If you still have doubts, ask in the [[Mailing lists | mailing list]]. But ask after doing your homework, i.e. trying yourself.
# Use an email address which is reachable for replies, i.e. don't submit patches from ''root@myserver.example.com''.
# Be patient after submitting a patch. Don't expect same day replies. Ping after a week or so.
# Always submit fixes '''first''' in a patch series. This way they could be applied independently of the rest of the series.

= Commit style =

A patch contains some metadata which is really important for us. This metadata is mainly 3 elements: title, description and Signed-off-by: lines.

Example:

<pre>
src: fix use after free bug

Due to this code branch never being tested before, there was a hidden user-after-free bug.
Fix it now and include some test cases to execute this code path.

Signed-off-by: One Developer <onedeveloper@example.com>
</pre>

== Title ==

Should give context of what component is being updated. Just by reading the title, the reader should be able to know ''what'' you are touching.

A good idea is to follow this pattern:

<pre>
component: subcomponent: message
</pre>

If the patch is a fix, include the '''fix''' word as the first one in the message:

<pre>
component: subcomponent: fix [...]
</pre>

If you are touching the whole project code, use the project name as component:

<pre>
nftables: switch all source code from C to Java
</pre>

Other examples:

<pre>
expr: drop unused code
</pre>
<pre>
evaluate: introduce extra step to verify whatever
</pre>
<pre>
main: config: cleanup warning messages
</pre>

== Message ==

The message of the patch should contain a complete explanation of what are you doing, since this may not be obvious from reading the code.
You should justify the change as well. Include results of tests if applicable.

Some examples:

<pre>
The code was not fast enough causing the system to block.
Solve this by implementing the algorithm foo.

Previous to this patch, an execution takes 100ms
After this patch, the same execution takes 10ms
</pre>

Again, be explicit in this description. People unfamiliar with the codebase could be reading.

== Footer lines ==

All commits should contain at least one 'Signed-off-by:' line. This comes directly from the Linux Kernel submission guidelines and indicates
that you are responsible of the code you are submitting, among other things.

Other footer lines you should include, if applicable:

* Fixing a previous commit, you would likely need:
<pre>
Fixes: be441e1ffdc24 ("src: add debugging mask to context structure")
</pre>
* Fixing a bugzilla bug, you would use:
<pre>
Closes: https://bugzilla.netfilter.org/show_bug.cgi?id=1145
</pre>
* If someone give additional testing to your patch:
<pre>
Tested-by: Someone <someone@example.com>
</pre>
* If someone ACK your change:
<pre>
Acked-by: Someone <someone@example.com>
</pre>
* If the change was suggested by other person
<pre>
Suggested-by: Other Person <other@example.com>
</pre>
* If you fix a bug thanks to the report of someone else, give credits to that person!
<pre>
Reported-by: Someone Else <else@example.com>
</pre>

== Examples ==

These are great real-life examples of commit/patch:

http://git.netfilter.org/nftables/commit/?id=bada2f9c182dddf72a6d3b7b00c9eace7eb596c3
<pre>
evaluate: merge nested set flags

A set may contain a nested set element definition, merge the nested set
flags so we don't hit:

BUG: invalid data expression type range
nft: netlink.c:400: netlink_gen_data: Assertion `0' failed.
Aborted

With the following example ruleset:

define dnat_ports = { 1234-1567 }
define port_allow = {
53, # dns
$dnat_ports, # dnat
}

add rule x y tcp dport $port_allow accept

Closes: https://bugzilla.netfilter.org/show_bug.cgi?id=1145
Fixes: a6b75b837f5e ("evaluate: set: Allow for set elems to be sets")
Signed-off-by: Pablo Neira Ayuso <pablo@netfilter.org>
</pre>

http://git.netfilter.org/nftables/commit/?id=4ae0b6dc90d16b4d93a4e8b6703f23dcf2467b85
<pre>
statement: fix print of ip dnat address

the change causes non-ipv6 addresses to not be printed at all in case
a nfproto was given.

Also add a test case to catch this.

Closes: https://bugzilla.netfilter.org/show_bug.cgi?id=1117
Fixes: 5ab0e10fc6e2c22363a ("src: support for RFC2732 IPv6 address format with brackets")
Signed-off-by: Florian Westphal <fw@strlen.de>
Acked-by: Pablo Neira Ayuso <pablo@netfilter.org>

</pre>

= Patch series =

If you submit several changes in a row which are related, consider using a patch series.
A cover letter is usually recommended, but not always required. You can skip the cover letter if
the patch series is small (2-5 patches) and each individual patch is small and well explained.

Writing a cover letter is mandatory if your patch series introduces a really big change to the codebase.

= Email submission =

Git can email things directly if well configured. Please, read some docs on the topic (see '''External links''').

Take into account that the email subject should contain a tag like this:

<pre>
[PATCH] commit title
</pre>

You should include the repository name in this tag:

<pre>
[nft PATCH] commit title
[libnftnl PATCH] commit title
[conntrack-tools PATCH] commit title
</pre>

Also, if you are in a series, the tag will include some additional numbers:
<pre>
[nft PATCH 1/3] commit title
[nft PATCH 2/3] commit title
[libnftnl PATCH 3/3] commit title
</pre>

If your patch is a RFC (just an idea, request for comments), include that as well:

<pre>
[RFC nft PATCH 1/2] commit title
[RFC nft PATCH 2/2] commit title
</pre>

If you version your patchset (i.e. changes are requested or whatever), state that as well:

<pre>
[nft PATCH 1/2 v2] commit title
[nft PATCH 2/2 v2] commit title
</pre>

In this last case, some changelog should be included before the diffstat included in the patch.

= See also =

Please, read this useful information:

* [[Bug reporting]]
* [https://git-scm.com/ Git main website]
* [https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/Documentation/process/coding-style.rst Linux Kernel docs - coding style]
* [https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/Documentation/process/submitting-patches.rst Linux Kernel docs - submitting patches]
* [[Development environment]]
* [[Contributing]]
* [[Mailing lists]]
* [[Licensing]]

← Older revision		Revision as of 13:09, 14 July 2019
Line 232:		Line 232:
	* [[Portal:DeveloperDocs/Development_environment \| Development environment]]		* [[Portal:DeveloperDocs/Development_environment \| Development environment]]
	* [[Portal:DeveloperDocs/Contributing \| Contributing]]		* [[Portal:DeveloperDocs/Contributing \| Contributing]]
			* [http://patchwork.ozlabs.org/project/netfilter-devel/list/ patchwork patch management system]

Portal:DeveloperDocs/Patch submission guidelines - Revision history

Arturo: /* See also */ add link to patchwork

Arturo: bold sentence about git and linux coding style

Arturo: refresh page with interlinks etc

Arturo: create page