Re: [dpdk-dev] [PATCH] doc: add contributors guide

[Thomas Monjalon <thomas.monjalon@6wind.com>]

Hi John,

2015-10-15 17:51, John McNamara:
> Add a document to explain the DPDK patch submission and review process.

Thanks

> +There are also DPDK mailing lists for:
> +
> +* users: `general usage questions <http://dpdk.org/ml/listinfo/users>`_.
> +* announce: `release announcements <http://dpdk.org/ml/listinfo/announce>`_ (also forwarded to the dev list).
> +* dts: `test suite reviews and discussions <http://dpdk.org/ml/listinfo/dts>`_.

I think these lists are not relevant for patch submission.

> +* test-reports: `test reports <http://dpdk.org/ml/listinfo/test-report>`_ (from continuous integration testing).
[...]
> +Getting the Source Code
> +-----------------------
> +
> +The source code can be cloned using either of the following::
> +
> +    git clone git://dpdk.org/dpdk
> +
> +    git clone http://dpdk.org/git/dpdk
> +
> +You can also `browse the source code <http://www.dpdk.org/browse/dpdk/tree/>`_ online.

The online browse doesn't help for patch contribution.

[...]
> +* If you add new files or directories you should add your name to the ``MAINTAINERS`` file.

yes

> +* If your changes add new external functions then they should be added to the local ``version.map`` file.
> +  See the :doc:`Guidelines for ABI policy and versioning </contributing/versioning>`.
> +
> +* Most changes will require an addition to the release notes in ``doc/guides/rel_notes/``.
> +  See the :ref:`Release Notes section of the Documentation Guidelines <doc_guidelines>` for details.

s/Most/Important/ ?

> +* Don’t break compilation between commits with forward dependencies.
> +  Each commit should compile on its own to allow for ``git bisect`` and continuous integration testing.

no, please, don't break compilation :)

> +* Add tests to the the ``app/test`` unit test framework where possible.
> +
> +* Add documentation, if required, in the form of Doxygen comments or a User Guide in RST format.

s/required/relevant/ ?

> +The commits should be separated into logical patches in a patchset.

Yes

> +In general commits should be separated based on their directory such as ``lib``, ``drivers``, ``scripts`` although
> +some of these, such as ``drivers`` may require finer grained separation.

No. The directory is not so important.
It must be easy to review first.
If changes are not so big and do not require specific explanations,
it's better to keep things together in the same patch.
A good way of thinking about patch split is to consider backports:
will it be easy to backport this change with its dependencies?
will it be easy to backport this feature/fix without useless bloat?

> +The easiest way of determining this is to do a ``git log`` on changed or similar files.

Yes

> +Example of a logical patchset separation::
> +
> +   [patch 1/6]    ethdev: add support for ieee1588 timestamping
> +   [patch 2/6]    e1000: add support for ieee1588 timestamping
> +   [patch 3/6]    ixgbe: add support for ieee1588 timestamping
> +   [patch 4/6]    i40e: add support for ieee1588 timestamping
> +   [patch 5/6]    app/testpmd: refactor ieee1588 forwarding
> +   [patch 6/6]    doc: document ieee1588 forwarding mode

The doc must be committed with the API change (ethdev).
Splitting driver implementations is useful only if they are really big or
require some specific explanations in the commit message.

> +* The summary line should be lowercase.

The acronyms can be uppercase.

> +  For example::
> +
> +     ixgbe: fix bug in xyz

After "fix", the word "bug" is useless.
It's better to briefly explain the impact of the bug, e.g. "fix RSS on 32-bit".
So people interested in RSS or 32-bit will look at this fix.

> +     ixgbe: add refcount to foo struct

Generally, using the name of a struct, a variable or a file in the title
reveals that you don't know how to explain your change simply.
The implementation details may be explained in the long message.
The title must help to catch the area and the impact of the change.

> +If you are submitting a RFC draft of a feature you can use ``[RFC]`` instead of ``[PATCH]``.

A RFC may be incomplete.
It helps to have feedbacks before doing more.

> +* You must provide a body to the commit message after the subject/summary line.
> +  Do not leave it blank.

When it is totally obvious, the Signed-off is enough.

> +* When fixing a regression, it is a good idea to reference the id of the commit which introduced the bug.
> +  You can generate the required text as follows::
> +
> +     git log -1 COMMIT_ID --abbrev=12 --format='Fixes: %h ("%s")'

git alias: fixline = log -1 --abbrev=12 --format='Fixes: %h (\"%s\")'

> +     Fixes: a4024448efa6 ("i40e: add ieee1588 timestamping")

Yes it will help the backports.

> +* When fixing an error or warning it is useful to add the error message or output.

The steps to reproduce the bugs are also required.

> +* ``Reported-by:`` The reporter of the issue.
> +* ``Tested-by:`` The tester of the change.
> +* ``Reviewed-by:`` The reviewer of the change.
> +* ``Suggested-by:`` The person who suggested the change.

Yes, and Acked-by:
When it is commented between 2 versions of the patch, it can be added in the
new version if it is still relevant.

> +Cover letters are useful for explaining a patchset.

And it helps to have a correct threading of the patches.

> +Version 2 and later of a patchset should also include a short log of the changes so the reviewer knows what has changed.
> +This can go either in the cover letter on the annotations.

s/on/or/

> +The kernel guidelines that are tested by ``checkpatch`` don't match the DPDK Coding Style guidelines exactly but
> +they provide a good indication of conformance.
> +Warnings about not using kernel data types or about split strings can be ignored::
> +
> +   /path/checkpatch.pl --ignore PREFER_KERNEL_TYPES,SPLIT_STRING -q files*.patch

OK
I plan to suggest a script with more checkpatch configurations.

We should enforce using "make test" before sending.

> +Patches should be sent to the mailing list using ``git send-email``.
> +This will require a working and configured ``sendmail`` or similar application.

No, you can configure an external SMTP:
	smtpuser = name@domain.com
	smtpserver = smtp.domain.com
	smtpserverport = 465
	smtpencryption = ssl

> +If the patches are a change to existing files then you should CC the maintainer(s) of the changed files.
> +The appropriate maintainer can be found in the ``MAINTAINERS`` file::
> +
> +   git send-email --to dev@dpdk.org --cc maintainer@some.org 000*.patch

I would say to send --to the maintainers and -cc dev@dpdk.org.
Some maintainers can have stronger filter if their name is in the "To" field.

> +If the patch is in relation to a previous email thread you can add it to the same thread using the Message ID::
> +
> +   git send-email --to dev@dpdk.org --in-reply-to <1234-foo@bar.com> 000*.patch

Yes please.
s/can/should/

> +Experienced commiters may send patches directly with ``git send-email`` without the ``git format-patch`` step.

The options --annotate and "confirm = always" are recommended to check before sending.

> +The more work you put into the previous steps the easier it will be to get a patch accepted.

Yes :)

> +#. Submit the patch.

Check the automatic test reports in the coming hours.

> +#. Wait for review comments. While you are waiting review some other patches.

> +#. If the patch is deemed suitable for merging by the relevant maintainer(s) or other developers they will ``ack``
> +   the patch with an email that includes something like::

We don"t use Reviewed-by a lot.
My understanding is that "Acked-by" doesn't mean it has been fully reviewed and tested.
But Reviewed-by is stronger without implying that we think it's the best solution.
It's an interpretation. Should it be explained here?

> +#. If the patch isn't deemed suitable based on being out of scope or conflicting with existing functionality
> +   it may receive a ``nack``.
> +   In this case you will need to make a more convincing technical argument in favor of your patches.

More generally, a patch should not be accepted if there are some comments not
addressed by a new version or some strong arguments.

> +#. Acked patches will be merged in the next merge window.

Next or current?