On 24 Jun 2026, at 14:41, Eelco Chaudron via dev wrote:
> 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.
Hi Ilya,
Offline you asked me if these texts were copied from netdev
documentation. Just to confirm here that they are not, the text is
actually different (even in this part). I guess you thought so due to
the "branch closed" part here. We do not really close the branch, we
just do not apply the patches. Maybe I should change the text to the
below.
Let me know your thoughts, and I can apply it on commit.
``Deferred``
The patch cannot be applied right now, for example due to an unresolved
dependency. 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
_______________________________________________
dev mailing list
[email protected]
https://mail.openvswitch.org/mailman/listinfo/ovs-dev
