On 22 Jul 2026, at 19:42, Ilya Maximets wrote:
> On 7/2/26 3:46 PM, Eelco Chaudron wrote:
>>
>>
>> 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
>>> -------
>
> It looks a little strange that the Example for the initial posting goes
> after the 'Posting New Versions' and the 'After Submitting' sections.
> It belongs to the 'Patch' section. The new section might be better placed
> at the end of the document.
>
>>>
>>> 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.
>
> Maybe 're-posted' ?
>
> Otherwise, I think it's a good addition to the docs. Thanks for putting
> this together!
>
> With the above nits addressed:
>
> Acked-by: Ilya Maximets <[email protected]>
Thanks Ilya, for the review, with your suggested changes applied to main!
//Eelco
_______________________________________________
dev mailing list
[email protected]
https://mail.openvswitch.org/mailman/listinfo/ovs-dev
