Add documentation explaining what patch authors should do after submitting a patch to the ovs-dev mailing list.
- patchwork.rst: Add a 'Patch States' section describing each Patchwork state (New, Under Review, Changes Requested, Accepted, Rejected, Superseded, Deferred) from the author's perspective. - submitting-patches.rst: Add 'Posting New Versions' and 'After Submitting' sections, covering how to post a revised patch with a versioned subject and changelog, and how to monitor patch state in Patchwork after submission. - faq/contributing.rst: Add a Q&A entry answering "I submitted a patch, what happens next?" with a brief summary and cross-references to the above. Signed-off-by: Eelco Chaudron <[email protected]> --- Documentation/faq/contributing.rst | 42 +++++++++---------- .../contributing/submitting-patches.rst | 38 +++++++++++++++++ Documentation/internals/patchwork.rst | 40 ++++++++++++++++++ 3 files changed, 99 insertions(+), 21 deletions(-) diff --git a/Documentation/faq/contributing.rst b/Documentation/faq/contributing.rst index 1790a3c20..798f83be0 100644 --- a/Documentation/faq/contributing.rst +++ b/Documentation/faq/contributing.rst @@ -151,27 +151,10 @@ Q: How do I apply patches from email? fi | git am "$@" rm "$tmp" - Another way to apply emailed patches is to use the ``pwclient`` program, - which can obtain patches from patchwork and apply them directly. Download - ``pwclient`` at https://patchwork.ozlabs.org/project/openvswitch/. You - probably want to set up a ``.pwclientrc`` that looks something like this:: - - [options] - default=openvswitch - signoff=true - - [openvswitch] - url=https://patchwork.ozlabs.org/xmlrpc/ - - After you install ``pwclient``, you can apply a patch from patchwork with - ``pwclient git-am #``, where # is the patch's number. (This fails with - certain patches that contain form-feeds, due to a limitation of the protocol - underlying ``pwclient``.) - - Another way to apply patches directly from patchwork which supports applying - patch series is to use the ``git-pw`` program. It can be obtained with - ``pip install git-pw``. Alternative installation instructions and general - documentation can be found at + Another way to apply emailed patches is to use the ``git-pw`` program, + which can obtain patches from patchwork and apply them directly. It can be + obtained with ``pip install git-pw``; alternative installation instructions + and general documentation can be found at https://patchwork.readthedocs.io/projects/git-pw/en/latest/. You need to use your openvswitch patchwork login or create one at https://patchwork.ozlabs.org/register/. The following can then be set on @@ -186,3 +169,20 @@ Q: How do I apply patches from email? Patch series can be listed with ``git-pw series list`` and applied with ``git-pw series apply #``, where # is the series number. Individual patches can be applied with ``git-pw patch apply #``, where # is the patch number. + + For more information on patchwork, see :doc:`/internals/patchwork`. + +Q: I submitted a patch, what happens next? + + A: After sending your patch to the ovs-dev mailing list, reviewers and + maintainers will read it and may reply with comments, questions, or an + ``Acked-by:`` indicating approval. The patch's status is tracked in + `Patchwork <https://patchwork.ozlabs.org/project/openvswitch/list/>`__; + you should monitor it there rather than waiting passively. + + If the patch is marked **Changes Requested**, the review discussion has + concluded that a revised version is needed. Post a new version as a + separate email thread with an incremented version tag (e.g. ``[PATCH v2]``) + and a short changelog describing what changed. See + :doc:`/internals/contributing/submitting-patches` for full guidance on + posting new versions and the meaning of each patchwork state. diff --git a/Documentation/internals/contributing/submitting-patches.rst b/Documentation/internals/contributing/submitting-patches.rst index c472a72bb..5e2d4f4bb 100644 --- a/Documentation/internals/contributing/submitting-patches.rst +++ b/Documentation/internals/contributing/submitting-patches.rst @@ -452,6 +452,44 @@ leading/trailing whitespace, missing signoffs, some improper formatted patch files). For Linux datapath code, it is a good idea to use the Linux script ``checkpatch.pl``. +.. _posting-new-versions: + +Posting New Versions +-------------------- + +When review feedback requires changes, post a revised patch as a new email +thread (do not reply to the original thread). Increment the version number in +the subject prefix, e.g. ``[PATCH v2]``, ``[PATCH v3]``, and so on. Include a +changelog below the ``---`` separator line describing what changed since the +previous version. For example:: + + --- + v3: Addressed review comments from Jane Doe: + - Fixed off-by-one in foo(). + + v2: Addressed review comments from John Doe: + - Reworded commit message to clarify intent. + - Replaced open-coded loop with existing helper foo(). + +Always resend the complete patch or series, not just the changed parts. Before +reposting, make sure the review thread on the previous version has gone quiet; +do not post a new version while active discussion is still ongoing unless a +reviewer explicitly asks you to. + +After Submitting +---------------- + +After sending your patch to the mailing list, keep an eye on its state in +`Patchwork <https://patchwork.ozlabs.org/project/openvswitch/list/>`__. +Maintainers update states manually as review progresses; see +:ref:`patch-states` in :doc:`/internals/patchwork` for what each state means. + +If the patch is marked **Changes Requested**, post a revised version as +described in :ref:`posting-new-versions` above. + +If you have not received any feedback for a while, send a ping to the mailing +list. + Example ------- diff --git a/Documentation/internals/patchwork.rst b/Documentation/internals/patchwork.rst index bc5c89c96..870c547c3 100644 --- a/Documentation/internals/patchwork.rst +++ b/Documentation/internals/patchwork.rst @@ -43,6 +43,46 @@ vSwitch: __ https://github.com/getpatchwork/patchwork __ https://patchwork.ozlabs.org/project/openvswitch/list/ +.. _patch-states: + +Patch States +------------ + +Maintainers update the state of a patch in Patchwork manually to reflect its +current status in the review process. As a patch author, you should monitor +your patch's state after submission. The states you are most likely to +encounter are: + +``New`` + The patch has been received and not yet triaged. + +``Under Review`` + The patch is being actively reviewed by a maintainer or reviewer. + +``Changes Requested`` + Review discussion has concluded that the patch needs changes before it can + be accepted. You should revise your patch and post a new version (see + :ref:`posting-new-versions`). + +``Accepted`` + The patch has been applied to the Open vSwitch repository. No further + action is needed. + +``Rejected`` + The patch will not be applied. The review thread should explain why. + +``Superseded`` + A newer version of the patch has been posted, making this version obsolete. + +``Deferred`` + The patch cannot be applied right now, for example due to an unresolved + dependency or because it targets a branch that is currently closed. It + should be reposted when the blocking condition is resolved. + +If your patch has been in ``New`` or ``Under Review`` state for an extended +period without any feedback, check whether the thread went quiet and send a +polite ping to the mailing list. + .. _git-pw: git-pw -- 2.54.0 _______________________________________________ dev mailing list [email protected] https://mail.openvswitch.org/mailman/listinfo/ovs-dev
