Skip to contentSkip to conversation

doc: develop: process: Clarify some patch editing expectations

PATCH Superseded Tom Rini 2 participants 18 messages Jan 16 – Jan 21

lore
Share & tools
lore

Tom Rini

author
#0 lore raw

v2 cover doc: develop: process: Clarify some patch editing expectations

Hey all,

This is a v2 of
https://lore.kernel.org/u-boot/[email protected]/
where I've rewritten everything from scratch.

The goal of this series is to make it clear that custodians are only supposed to make very limited changes to patches prior to merging. This ends up being a small series in that with the current structure of the document there's not a good place to do that. So this changes the current document to have the "workflow" section refer back to the custodian section when discussing the state of a patch itself, converts what we have today to bullet points and then states the limited circumstances where custodians should make in-line edits while applying.

Signature · 1 line
Tom
author
#1 lore raw

PATCH v2 1/3 doc: develop: process: Move the existing block about patch application

We have a long block about the expectations and feedback about a patch applying, or not, as part of the Custodian workflow. Move this to the Custodians section from the Workflow of a custodian section.

---
Changes in v2:
- New patch.

---
 doc/develop/process.rst | 22 +++++++++++++---------
 1 file changed, 13 insertions(+), 9 deletions(-)
doc/develop/process.rst +13 -9
index 4bfbf0eb9c63..81e1aa7e34db 100644
@@ -143,6 +143,17 @@ reworked/resubmitted, or if it was rejected. However, if a submitter
 feels it has been too long since posting their patch and not received
 any feedback, it is OK to follow-up and ask.
 
+Another form of feedback is about applying the patch itself to the
+source tree.  The custodian is expected to put in a "best effort" if a
+patch does not apply cleanly, but can be made to apply still. It is up
+to the custodian to decide how recent of a commit the patch must be
+against. It is acceptable to request patches against the last officially
+released version of U-Boot or newer. Of course a custodian can also
+accept patches against older code. It can be difficult to find the
+correct balance between putting too much work on the custodian or too
+much work on an individual submitting a patch when something does not
+apply cleanly.
+
 Review Process, Git Tags
 ------------------------
 
@@ -236,15 +247,8 @@ like this:
 
    #. U-Boot Philosophy, as documented in :doc:`designprinciples`.
 
-   #. Applies cleanly to the source tree.  The custodian is expected to put in
-      a "best effort" if a patch does not apply cleanly, but can be made to apply
-      still.  It is up to the custodian to decide how recent of a commit the
-      patch must be against.  It is acceptable to request patches against the
-      last officially released version of U-Boot or newer.  Of course a
-      custodian can also accept patches against older code.  It can be
-      difficult to find the correct balance between putting too much work on
-      the custodian or too much work on an individual submitting a patch when
-      something does not apply cleanly.
+   #. Can be applied easily to the source tree, as documented in the
+      :ref:`custodians` section.
 
    #. Passes :doc:`ci_testing` as this checks for new warnings and other issues.
 
Signature · 1 line
2.43.0
#2 lore raw

Re: [PATCH v2 1/3] doc: develop: process: Move the existing block about patch application

Hi Tom,

Quoted 17 lines · Tom Rini

We have a long block about the expectations and feedback about a patch applying, or not, as part of the Custodian workflow. Move this to the Custodians section from the Workflow of a custodian section.

---
Changes in v2:
- New patch.

---
  doc/develop/process.rst | 22 +++++++++++++---------
  1 file changed, 13 insertions(+), 9 deletions(-)
doc/develop/process.rst +0 -0
index 4bfbf0eb9c63..81e1aa7e34db 100644

doc/develop/process.rst reworked/resubmitted, or if it was rejected. However, if a submitter · line 146

Quoted 4 lines
doc/develop/process.rst +1 -0
@@ -143,6 +143,17 @@ reworked/resubmitted, or if it was rejected. However, if a submitter
  feels it has been too long since posting their patch and not received
  any feedback, it is OK to follow-up and ask.
 
+Another form of feedback is about applying the patch itself to the

The wording is odd to me, applying the patch isn't a form of feedback? I would assume feedback to be some interaction between the custodian and the submitter.

Would

"""
Another form of feedback can happen while applying the patch itself to the source tree. """

help (since we specify later that the custodian can request a rebase if they feel like it)?

doc/develop/process.rst reworked/resubmitted, or if it was rejected. However, if a submitter · line 147

Quoted 1 line
doc/develop/process.rst +1 -0
+source tree.  The custodian is expected to put in a "best effort" if a

Unnecessary double whitespace before "The custodian".

We could also add a label before this section so we can refer to it exactly later in this patch. See ".. _dco:" in the current rST file. Not a blocker.

Looks ok to me. (Just moving text around after all :) )

Cheers,
Quentin

author
#3 lore raw

Re: [PATCH v2 1/3] doc: develop: process: Move the existing block about patch application

Quoted 38 lines · Quentin Schulz

Hi Tom,

Quoted 17 lines · Tom Rini

We have a long block about the expectations and feedback about a patch applying, or not, as part of the Custodian workflow. Move this to the Custodians section from the Workflow of a custodian section.

---
Changes in v2:
- New patch.

---
  doc/develop/process.rst | 22 +++++++++++++---------
  1 file changed, 13 insertions(+), 9 deletions(-)
doc/develop/process.rst +0 -0
index 4bfbf0eb9c63..81e1aa7e34db 100644

doc/develop/process.rst reworked/resubmitted, or if it was rejected. However, if a submitter · line 145

Quoted 3 lines
doc/develop/process.rst +1 -0
@@ -143,6 +143,17 @@ reworked/resubmitted, or if it was rejected. However, if a submitter
  feels it has been too long since posting their patch and not received
  any feedback, it is OK to follow-up and ask.
+Another form of feedback is about applying the patch itself to the

The wording is odd to me, applying the patch isn't a form of feedback? I would assume feedback to be some interaction between the custodian and the submitter.

Would

"""
Another form of feedback can happen while applying the patch itself to the source tree.
"""

help (since we specify later that the custodian can request a rebase if they feel like it)?

Quoted 8 lines

doc/develop/process.rst reworked/resubmitted, or if it was rejected. However, if a submitter · line 147

Quoted 1 line
doc/develop/process.rst +1 -0
+source tree.  The custodian is expected to put in a "best effort" if a

Unnecessary double whitespace before "The custodian".

We could also add a label before this section so we can refer to it exactly later in this patch. See ".. _dco:" in the current rST file. Not a blocker.

Looks ok to me. (Just moving text around after all :) )

To be clear, since you see in the next patch I remove the awkward line (which I agree is awkward, but I needed to move the existing text with minimal changes), and further clarify this section as well, I'm not reworking this more in v3.

Signature · 1 line
Tom
author
#4 lore raw

PATCH v2 2/3 doc: develop: process: Rework the custodian feedback section

In reply to Tom Rini

Now that we have two items here, rework this slightly to be using bullet points, and so easier to expand on.

---
Changes in v2:
- New patch.

---
 doc/develop/process.rst | 43 +++++++++++++++++++++--------------------
 1 file changed, 22 insertions(+), 21 deletions(-)
doc/develop/process.rst +22 -21
index 81e1aa7e34db..6f5bdd3db957 100644
@@ -132,27 +132,28 @@ It is their responsibility to pick up patches from the mailing list
 that fall into their responsibility, and to process these.
 
 A very important responsibility of each custodian is to provide
-feedback to the submitter of a patch about what is going on: if the
-patch was accepted, or if it was rejected (which exact list of
-reasons), if it needs to be reworked (with respective review
-comments). Even a "I have no time now, will look into it later"
-message is better than nothing. Also, if there are remarks to a
-patch, these should leave no doubt if they were just comments and the
-patch will be accepted anyway, or if the patch should be
-reworked/resubmitted, or if it was rejected. However, if a submitter
-feels it has been too long since posting their patch and not received
-any feedback, it is OK to follow-up and ask.
-
-Another form of feedback is about applying the patch itself to the
-source tree.  The custodian is expected to put in a "best effort" if a
-patch does not apply cleanly, but can be made to apply still. It is up
-to the custodian to decide how recent of a commit the patch must be
-against. It is acceptable to request patches against the last officially
-released version of U-Boot or newer. Of course a custodian can also
-accept patches against older code. It can be difficult to find the
-correct balance between putting too much work on the custodian or too
-much work on an individual submitting a patch when something does not
-apply cleanly.
+feedback to the submitter of a patch about what is going on:
+
+  * If the patch was accepted, or if it was rejected (which exact list
+    of reasons), if it needs to be reworked (with respective review
+    comments). Even a "I have no time now, will look into it later"
+    message is better than nothing. Also, if there are remarks to a
+    patch, these should leave no doubt if they were just comments and
+    the patch will be accepted anyway, or if the patch should be
+    reworked/resubmitted, or if it was rejected. However, if a submitter
+    feels it has been too long since posting their patch and not
+    received any feedback, it is OK to follow-up and ask.
+
+  * If the patch itself can still be applied to the tree. The custodian
+    is expected to put in a "best effort" if a patch does not apply
+    cleanly, but can be made to apply still. It is up to the custodian
+    to decide how recent of a commit the patch must be against. It is
+    acceptable to request patches against the last officially released
+    version of U-Boot or newer. Of course a custodian can also accept
+    patches against older code. It can be difficult to find the correct
+    balance between putting too much work on the custodian or too much
+    work on an individual submitting a patch when something does not
+    apply cleanly.
 
 Review Process, Git Tags
 ------------------------
Signature · 1 line
2.43.0
Reviewed-by on v2 2/3
#5 lore raw

Re: [PATCH v2 2/3] doc: develop: process: Rework the custodian feedback section

Hi Tom,

Quoted 33 lines · Tom Rini

Now that we have two items here, rework this slightly to be using bullet points, and so easier to expand on.

---
Changes in v2:
- New patch.

---
  doc/develop/process.rst | 43 +++++++++++++++++++++--------------------
  1 file changed, 22 insertions(+), 21 deletions(-)
doc/develop/process.rst +0 -14
index 81e1aa7e34db..6f5bdd3db957 100644
@@ -132,27 +132,28 @@ It is their responsibility to pick up patches from the mailing list
  that fall into their responsibility, and to process these.
 
  A very important responsibility of each custodian is to provide
-feedback to the submitter of a patch about what is going on: if the
-patch was accepted, or if it was rejected (which exact list of
-reasons), if it needs to be reworked (with respective review
-comments). Even a "I have no time now, will look into it later"
-message is better than nothing. Also, if there are remarks to a
-patch, these should leave no doubt if they were just comments and the
-patch will be accepted anyway, or if the patch should be
-reworked/resubmitted, or if it was rejected. However, if a submitter
-feels it has been too long since posting their patch and not received
-any feedback, it is OK to follow-up and ask.
-
-Another form of feedback is about applying the patch itself to the
-source tree.  The custodian is expected to put in a "best effort" if a
-patch does not apply cleanly, but can be made to apply still. It is up

doc/develop/process.rst It is their responsibility to pick up patches from the mailing list · line 137

Quoted 10 lines
doc/develop/process.rst +3 -7
-to the custodian to decide how recent of a commit the patch must be
-against. It is acceptable to request patches against the last officially
-released version of U-Boot or newer. Of course a custodian can also
-accept patches against older code. It can be difficult to find the
-correct balance between putting too much work on the custodian or too
-much work on an individual submitting a patch when something does not
-apply cleanly.
+feedback to the submitter of a patch about what is going on:
+
+  * If the patch was accepted, or if it was rejected (which exact list

For another patch as this isn't added/modified by this patch, but wasn't "with" meant here instead of "which"?

doc/develop/process.rst It is their responsibility to pick up patches from the mailing list · line 147

Quoted 10 lines
doc/develop/process.rst +10 -0
+    of reasons), if it needs to be reworked (with respective review
+    comments). Even a "I have no time now, will look into it later"
+    message is better than nothing. Also, if there are remarks to a
+    patch, these should leave no doubt if they were just comments and
+    the patch will be accepted anyway, or if the patch should be
+    reworked/resubmitted, or if it was rejected. However, if a submitter
+    feels it has been too long since posting their patch and not
+    received any feedback, it is OK to follow-up and ask.
+
+  * If the patch itself can still be applied to the tree. The custodian

Ah, the wording I complained about in patch 1 is gone, so i guess you can ignore it. I don't think it makes sense to nitpick about something that exists for one commit.

Thanks!
Quentin

author
#6 lore raw

Re: [PATCH v2 2/3] doc: develop: process: Rework the custodian feedback section

Quoted 40 lines · Quentin Schulz

Hi Tom,

Quoted 37 lines · Tom Rini

Now that we have two items here, rework this slightly to be using bullet points, and so easier to expand on.

---
Changes in v2:
- New patch.

---
  doc/develop/process.rst | 43 +++++++++++++++++++++--------------------
  1 file changed, 22 insertions(+), 21 deletions(-)
doc/develop/process.rst +0 -19
index 81e1aa7e34db..6f5bdd3db957 100644
@@ -132,27 +132,28 @@ It is their responsibility to pick up patches from the mailing list
  that fall into their responsibility, and to process these.
  A very important responsibility of each custodian is to provide
-feedback to the submitter of a patch about what is going on: if the
-patch was accepted, or if it was rejected (which exact list of
-reasons), if it needs to be reworked (with respective review
-comments). Even a "I have no time now, will look into it later"
-message is better than nothing. Also, if there are remarks to a
-patch, these should leave no doubt if they were just comments and the
-patch will be accepted anyway, or if the patch should be
-reworked/resubmitted, or if it was rejected. However, if a submitter
-feels it has been too long since posting their patch and not received
-any feedback, it is OK to follow-up and ask.
-
-Another form of feedback is about applying the patch itself to the
-source tree.  The custodian is expected to put in a "best effort" if a
-patch does not apply cleanly, but can be made to apply still. It is up
-to the custodian to decide how recent of a commit the patch must be
-against. It is acceptable to request patches against the last officially
-released version of U-Boot or newer. Of course a custodian can also
-accept patches against older code. It can be difficult to find the
-correct balance between putting too much work on the custodian or too
Quoted 8 lines

doc/develop/process.rst It is their responsibility to pick up patches from the mailing list · line 137

Quoted 5 lines
doc/develop/process.rst +3 -2
-much work on an individual submitting a patch when something does not
-apply cleanly.
+feedback to the submitter of a patch about what is going on:
+
+  * If the patch was accepted, or if it was rejected (which exact list

For another patch as this isn't added/modified by this patch, but wasn't "with" meant here instead of "which"?

Yes, and it was wrong in the old text but also it's a small enough change I'll just fold that in with v3.

Quoted 11 lines

doc/develop/process.rst It is their responsibility to pick up patches from the mailing list · line 147

Quoted 10 lines
doc/develop/process.rst +10 -0
+    of reasons), if it needs to be reworked (with respective review
+    comments). Even a "I have no time now, will look into it later"
+    message is better than nothing. Also, if there are remarks to a
+    patch, these should leave no doubt if they were just comments and
+    the patch will be accepted anyway, or if the patch should be
+    reworked/resubmitted, or if it was rejected. However, if a submitter
+    feels it has been too long since posting their patch and not
+    received any feedback, it is OK to follow-up and ask.
+
+  * If the patch itself can still be applied to the tree. The custodian
Quoted 5 lines

Ah, the wording I complained about in patch 1 is gone, so i guess you can ignore it. I don't think it makes sense to nitpick about something that exists for one commit.

Thanks.

Signature · 1 line
Tom
author
#7 lore raw

PATCH v2 3/3 doc: develop: process: Explain when/how Custodians may edit patches

In reply to Tom Rini

As seen with commit d503633a3676 ("Revert "doc: board: starfive: update jh7110 common description""), it has not always been clear what is and isn't allowed by custodians, and what the expectations are. To prevent further unintentional conflicts, document the limited cases where custodians are allowed to modify patches directly, and how to do that.

---
Changes in v2:
- New patch.

---
 doc/develop/process.rst | 6 ++++++
 1 file changed, 6 insertions(+)
doc/develop/process.rst +6 -0
index 6f5bdd3db957..775a855fd7a0 100644
@@ -144,6 +144,12 @@ feedback to the submitter of a patch about what is going on:
     feels it has been too long since posting their patch and not
     received any feedback, it is OK to follow-up and ask.
 
+    * A custodian may make spelling corrections, spacing fixes and other
+      obviously correct trivial changes. They must also in turn amend
+      the commit message noting their change inside of ``[]`` and add
+      their own ``Signed-off-by`` tag. All other changes must be handled
+      by another iteration of the patch, or follow-up patch.
+
   * If the patch itself can still be applied to the tree. The custodian
     is expected to put in a "best effort" if a patch does not apply
     cleanly, but can be made to apply still. It is up to the custodian
Signature · 1 line
2.43.0
#8 lore raw

Re: [PATCH v2 3/3] doc: develop: process: Explain when/how Custodians may edit patches

Hi Tom,

Quoted 19 lines · Tom Rini

As seen with commit d503633a3676 ("Revert "doc: board: starfive: update jh7110 common description""), it has not always been clear what is and isn't allowed by custodians, and what the expectations are. To prevent further unintentional conflicts, document the limited cases where custodians are allowed to modify patches directly, and how to do that.

---
Changes in v2:
- New patch.

---
  doc/develop/process.rst | 6 ++++++
  1 file changed, 6 insertions(+)
doc/develop/process.rst +0 -0
index 6f5bdd3db957..775a855fd7a0 100644

doc/develop/process.rst feedback to the submitter of a patch about what is going on: · line 148

Quoted 5 lines
doc/develop/process.rst +2 -0
@@ -144,6 +144,12 @@ feedback to the submitter of a patch about what is going on:
      feels it has been too long since posting their patch and not
      received any feedback, it is OK to follow-up and ask.
 
+    * A custodian may make spelling corrections, spacing fixes and other
+      obviously correct trivial changes. They must also in turn amend

I guess people will have a different interpretation as to *what* is an "obviously correct trivial change", based on the U-Boot git history, are there some commits that used the [] + SoB form that are fine or shouldn't have be made such that we can elaborate a bit more?

I think providing an example would be nice, e.g. the patch as on the mailing list and after being merged with changes (obviously one you think followed the rules here). This will make the section longer for sure but it'll be a visual cue that this is important.

I would suggest to require the custodian to notify as answer to the original patch if any change was made when merging the patch, even if the changes match the allowed list of changes listed above. What do you think?

Cheers,
Quentin

author
#9 lore raw

Re: [PATCH v2 3/3] doc: develop: process: Explain when/how Custodians may edit patches

Quoted 17 lines · Quentin Schulz

Hi Tom,

Quoted 14 lines · Tom Rini

As seen with commit d503633a3676 ("Revert "doc: board: starfive: update jh7110 common description""), it has not always been clear what is and isn't allowed by custodians, and what the expectations are. To prevent further unintentional conflicts, document the limited cases where custodians are allowed to modify patches directly, and how to do that.

---
Changes in v2:
- New patch.

---
  doc/develop/process.rst | 6 ++++++
  1 file changed, 6 insertions(+)
Quoted 12 lines

doc/develop/process.rst feedback to the submitter of a patch about what is going on: · line 147

Quoted 9 lines
doc/develop/process.rst +2 -0
index 6f5bdd3db957..775a855fd7a0 100644
@@ -144,6 +144,12 @@ feedback to the submitter of a patch about what is going on:
      feels it has been too long since posting their patch and not
      received any feedback, it is OK to follow-up and ask.
+    * A custodian may make spelling corrections, spacing fixes and other
+      obviously correct trivial changes. They must also in turn amend

I guess people will have a different interpretation as to *what* is an "obviously correct trivial change", based on the U-Boot git history, are

Yes, but this is intentional, honestly. In my other follow-up to E Shattow I mentioned there is other general process stuff we need as a project. Custodians are trusted members of the project and should have some leeway.

Quoted 2 lines

there some commits that used the [] + SoB form that are fine or shouldn't have be made such that we can elaborate a bit more?

Yes, we've made changes before that perhaps really shouldn't have been, or at least are questionable and should have had more discussion.

Quoted 8 lines

I think providing an example would be nice, e.g. the patch as on the mailing list and after being merged with changes (obviously one you think followed the rules here). This will make the section longer for sure but it'll be a visual cue that this is important.

I would suggest to require the custodian to notify as answer to the original patch if any change was made when merging the patch, even if the changes match the allowed list of changes listed above. What do you think?

I worry that we're making too many changes in the wrong direction, based on the problem that did occur. Which was a real problem. But it was also something that obviously fell outside of the "trivially correct" rule above, as it was adding new content.

Maybe, since the kind of spacing and spelling fixes I perform are the kind checkpatch complains about, and submitters are already supposed to use checkpatch, I should reword it to something like:

A custodian may make corrections to patches that checkpatch.pl (reference) notes, or may request the author re-submit after fixing them, at their discretion.

Signature · 1 line
Tom
#10 lore raw

Re: [PATCH v2 3/3] doc: develop: process: Explain when/how Custodians may edit patches

Hi Tom,

Quoted 31 lines · Tom Rini
Quoted 17 lines · Quentin Schulz

Hi Tom,

Quoted 14 lines · Tom Rini

As seen with commit d503633a3676 ("Revert "doc: board: starfive: update jh7110 common description""), it has not always been clear what is and isn't allowed by custodians, and what the expectations are. To prevent further unintentional conflicts, document the limited cases where custodians are allowed to modify patches directly, and how to do that.

---
Changes in v2:
- New patch.

---
   doc/develop/process.rst | 6 ++++++
   1 file changed, 6 insertions(+)
Quoted 12 lines

doc/develop/process.rst feedback to the submitter of a patch about what is going on: · line 147

Quoted 9 lines
doc/develop/process.rst +2 -0
index 6f5bdd3db957..775a855fd7a0 100644
@@ -144,6 +144,12 @@ feedback to the submitter of a patch about what is going on:
       feels it has been too long since posting their patch and not
       received any feedback, it is OK to follow-up and ask.
+    * A custodian may make spelling corrections, spacing fixes and other
+      obviously correct trivial changes. They must also in turn amend

I guess people will have a different interpretation as to *what* is an "obviously correct trivial change", based on the U-Boot git history, are

Quoted 5 lines

Yes, but this is intentional, honestly. In my other follow-up to E Shattow I mentioned there is other general process stuff we need as a project. Custodians are trusted members of the project and should have some leeway.

Ack.

Quoted 6 lines
Quoted 2 lines

there some commits that used the [] + SoB form that are fine or shouldn't have be made such that we can elaborate a bit more?

Yes, we've made changes before that perhaps really shouldn't have been, or at least are questionable and should have had more discussion.

I was just suggesting to provide real-life examples in the docs so people have some idea on how to format the commit log for example. I am neither intending nor expecting to review all commits ever made to check if some changes were made without approval from/feedback to the contributor.

Quoted 10 lines
Quoted 8 lines

I think providing an example would be nice, e.g. the patch as on the mailing list and after being merged with changes (obviously one you think followed the rules here). This will make the section longer for sure but it'll be a visual cue that this is important.

I would suggest to require the custodian to notify as answer to the original patch if any change was made when merging the patch, even if the changes match the allowed list of changes listed above. What do you think?

I worry that we're making too many changes in the wrong direction, based

It's always a fine balance to find. I guess this could be less "needed" if we encourage custodians to use b4 ty to send thank you notes when merging. Then one can simply go and check the commit themselves (or like you alluded in the v1, have tooling that can check that).

It's always easy to suggest processes when you won't have to follow them yourself, so I'm mostly asking questions or suggesting things.

Quoted 4 lines

on the problem that did occur. Which was a real problem. But it was also something that obviously fell outside of the "trivially correct" rule above, as it was adding new content.

Ack.

Quoted 8 lines

Maybe, since the kind of spacing and spelling fixes I perform are the kind checkpatch complains about, and submitters are already supposed to use checkpatch, I should reword it to something like:

A custodian may make corrections to patches that checkpatch.pl (reference) notes, or may request the author re-submit after fixing them, at their discretion.

This does help but only for code parts. We don't really have anything for the docs for example, or Kconfig, where typos or formatting errors can creep in. But I assume you intended to keep the whitespace/typo as general rules and just add the checkpatch requirement for everything that falls out of those rules?

We can always improve this over time, better have something explained now and refined later if custodians have questions or feedback to provide.

Cheers,
Quentin

author
#11 lore raw

Re: [PATCH v2 3/3] doc: develop: process: Explain when/how Custodians may edit patches

Quoted 45 lines · Quentin Schulz

Hi Tom,

Quoted 31 lines · Tom Rini
Quoted 17 lines · Quentin Schulz

Hi Tom,

Quoted 14 lines · Tom Rini

As seen with commit d503633a3676 ("Revert "doc: board: starfive: update jh7110 common description""), it has not always been clear what is and isn't allowed by custodians, and what the expectations are. To prevent further unintentional conflicts, document the limited cases where custodians are allowed to modify patches directly, and how to do that.

---
Changes in v2:
- New patch.

---
   doc/develop/process.rst | 6 ++++++
   1 file changed, 6 insertions(+)
Quoted 12 lines

doc/develop/process.rst feedback to the submitter of a patch about what is going on: · line 147

Quoted 9 lines
doc/develop/process.rst +2 -0
index 6f5bdd3db957..775a855fd7a0 100644
@@ -144,6 +144,12 @@ feedback to the submitter of a patch about what is going on:
       feels it has been too long since posting their patch and not
       received any feedback, it is OK to follow-up and ask.
+    * A custodian may make spelling corrections, spacing fixes and other
+      obviously correct trivial changes. They must also in turn amend

I guess people will have a different interpretation as to *what* is an "obviously correct trivial change", based on the U-Boot git history, are

Quoted 5 lines

Yes, but this is intentional, honestly. In my other follow-up to E Shattow I mentioned there is other general process stuff we need as a project. Custodians are trusted members of the project and should have some leeway.

Ack.

Quoted 3 lines
Quoted 2 lines

there some commits that used the [] + SoB form that are fine or shouldn't have be made such that we can elaborate a bit more?

Quoted 8 lines
Quoted 3 lines

Yes, we've made changes before that perhaps really shouldn't have been, or at least are questionable and should have had more discussion.

I was just suggesting to provide real-life examples in the docs so people have some idea on how to format the commit log for example. I am neither intending nor expecting to review all commits ever made to check if some changes were made without approval from/feedback to the contributor.

OK, thanks.

Quoted 9 lines
Quoted 9 lines
Quoted 8 lines

I think providing an example would be nice, e.g. the patch as on the mailing list and after being merged with changes (obviously one you think followed the rules here). This will make the section longer for sure but it'll be a visual cue that this is important.

I would suggest to require the custodian to notify as answer to the original patch if any change was made when merging the patch, even if the changes match the allowed list of changes listed above. What do you think?

Quoted 6 lines
Quoted 1 line

I worry that we're making too many changes in the wrong direction, based

It's always a fine balance to find. I guess this could be less "needed" if we encourage custodians to use b4 ty to send thank you notes when merging. Then one can simply go and check the commit themselves (or like you alluded in the v1, have tooling that can check that).

I think more custodians using b4 would help (as discussed slightly on irc, it offers good patchwork integration too), but thats not exactly what E Shattow was suggesting for a tooling idea, I believe. But I do believe more custodians using "b4 ty" would be helpful as it provides "is applied" along with "this commit hash".

Quoted 2 lines

It's always easy to suggest processes when you won't have to follow them yourself, so I'm mostly asking questions or suggesting things.

Yes, thanks. :)

Quoted 16 lines
Quoted 4 lines

on the problem that did occur. Which was a real problem. But it was also something that obviously fell outside of the "trivially correct" rule above, as it was adding new content.

Ack.

Quoted 8 lines

Maybe, since the kind of spacing and spelling fixes I perform are the kind checkpatch complains about, and submitters are already supposed to use checkpatch, I should reword it to something like:

A custodian may make corrections to patches that checkpatch.pl (reference) notes, or may request the author re-submit after fixing them, at their discretion.

Quoted 8 lines

This does help but only for code parts. We don't really have anything for the docs for example, or Kconfig, where typos or formatting errors can creep in. But I assume you intended to keep the whitespace/typo as general rules and just add the checkpatch requirement for everything that falls out of those rules?

We can always improve this over time, better have something explained now and refined later if custodians have questions or feedback to provide.

Note that checkpatch.pl will (modulo bugs) catch spelling problems globally. We now have it catching (some) spacing issues in Kconfig files, but since the kernel doesn't enforce something there it's local to us.

Signature · 1 line
Tom
author
#12 lore raw

v3 cover doc: develop: process: Clarify some patch editing expectations

In reply to Tom Rini

Hey all,

This is v3 of https://lore.kernel.org/u-boot/[email protected]
and there's only minor changes this time.

The goal of this series is to make it clear that custodians are only supposed to make very limited changes to patches prior to merging. This ends up being a small series in that with the current structure of the document there's not a good place to do that. So this changes the current document to have the "workflow" section refer back to the custodian section when discussing the state of a patch itself, converts what we have today to bullet points and then states the limited

Signature · 1 line
Tom
author
#13 lore raw

PATCH v3 1/3 doc: develop: process: Move the existing block about patch application

We have a long block about the expectations and feedback about a patch applying, or not, as part of the Custodian workflow. Move this to the Custodians section from the Workflow of a custodian section.

---
Changes in v2:
- New patch.

---
 doc/develop/process.rst | 22 +++++++++++++---------
 1 file changed, 13 insertions(+), 9 deletions(-)
doc/develop/process.rst +13 -9
index 4bfbf0eb9c63..81e1aa7e34db 100644
@@ -143,6 +143,17 @@ reworked/resubmitted, or if it was rejected. However, if a submitter
 feels it has been too long since posting their patch and not received
 any feedback, it is OK to follow-up and ask.
 
+Another form of feedback is about applying the patch itself to the
+source tree.  The custodian is expected to put in a "best effort" if a
+patch does not apply cleanly, but can be made to apply still. It is up
+to the custodian to decide how recent of a commit the patch must be
+against. It is acceptable to request patches against the last officially
+released version of U-Boot or newer. Of course a custodian can also
+accept patches against older code. It can be difficult to find the
+correct balance between putting too much work on the custodian or too
+much work on an individual submitting a patch when something does not
+apply cleanly.
+
 Review Process, Git Tags
 ------------------------
 
@@ -236,15 +247,8 @@ like this:
 
    #. U-Boot Philosophy, as documented in :doc:`designprinciples`.
 
-   #. Applies cleanly to the source tree.  The custodian is expected to put in
-      a "best effort" if a patch does not apply cleanly, but can be made to apply
-      still.  It is up to the custodian to decide how recent of a commit the
-      patch must be against.  It is acceptable to request patches against the
-      last officially released version of U-Boot or newer.  Of course a
-      custodian can also accept patches against older code.  It can be
-      difficult to find the correct balance between putting too much work on
-      the custodian or too much work on an individual submitting a patch when
-      something does not apply cleanly.
+   #. Can be applied easily to the source tree, as documented in the
+      :ref:`custodians` section.
 
    #. Passes :doc:`ci_testing` as this checks for new warnings and other issues.
 
Signature · 1 line
2.43.0
Reviewed-by on v3 1/3
#14 lore raw

Re: [PATCH v3 1/3] doc: develop: process: Move the existing block about patch application

Hi Tom,

Quoted 5 lines · Tom Rini

We have a long block about the expectations and feedback about a patch applying, or not, as part of the Custodian workflow. Move this to the Custodians section from the Workflow of a custodian section.

Thanks!
Quentin

author
#15 lore raw

PATCH v3 2/3 doc: develop: process: Rework the custodian feedback section

In reply to Tom Rini

Now that we have two items here, rework this slightly to be using bullet points, and so easier to expand on.

---
Changes in v3:
- Add Quentin's RB, correct a minor existing thinko Changes in v2:
- New patch.

---
 doc/develop/process.rst | 43 +++++++++++++++++++++--------------------
 1 file changed, 22 insertions(+), 21 deletions(-)
doc/develop/process.rst +22 -21
index 81e1aa7e34db..4159a945707e 100644
@@ -132,27 +132,28 @@ It is their responsibility to pick up patches from the mailing list
 that fall into their responsibility, and to process these.
 
 A very important responsibility of each custodian is to provide
-feedback to the submitter of a patch about what is going on: if the
-patch was accepted, or if it was rejected (which exact list of
-reasons), if it needs to be reworked (with respective review
-comments). Even a "I have no time now, will look into it later"
-message is better than nothing. Also, if there are remarks to a
-patch, these should leave no doubt if they were just comments and the
-patch will be accepted anyway, or if the patch should be
-reworked/resubmitted, or if it was rejected. However, if a submitter
-feels it has been too long since posting their patch and not received
-any feedback, it is OK to follow-up and ask.
-
-Another form of feedback is about applying the patch itself to the
-source tree.  The custodian is expected to put in a "best effort" if a
-patch does not apply cleanly, but can be made to apply still. It is up
-to the custodian to decide how recent of a commit the patch must be
-against. It is acceptable to request patches against the last officially
-released version of U-Boot or newer. Of course a custodian can also
-accept patches against older code. It can be difficult to find the
-correct balance between putting too much work on the custodian or too
-much work on an individual submitting a patch when something does not
-apply cleanly.
+feedback to the submitter of a patch about what is going on:
+
+  * If the patch was accepted, or if it was rejected (with exact list
+    of reasons), if it needs to be reworked (with respective review
+    comments). Even a "I have no time now, will look into it later"
+    message is better than nothing. Also, if there are remarks to a
+    patch, these should leave no doubt if they were just comments and
+    the patch will be accepted anyway, or if the patch should be
+    reworked/resubmitted, or if it was rejected. However, if a submitter
+    feels it has been too long since posting their patch and not
+    received any feedback, it is OK to follow-up and ask.
+
+  * If the patch itself can still be applied to the tree. The custodian
+    is expected to put in a "best effort" if a patch does not apply
+    cleanly, but can be made to apply still. It is up to the custodian
+    to decide how recent of a commit the patch must be against. It is
+    acceptable to request patches against the last officially released
+    version of U-Boot or newer. Of course a custodian can also accept
+    patches against older code. It can be difficult to find the correct
+    balance between putting too much work on the custodian or too much
+    work on an individual submitting a patch when something does not
+    apply cleanly.
 
 Review Process, Git Tags
 ------------------------
Signature · 1 line
2.43.0
author
#16 lore raw

PATCH v3 3/3 doc: develop: process: Explain when/how Custodians may edit patches

In reply to Tom Rini

As seen with commit d503633a3676 ("Revert "doc: board: starfive: update jh7110 common description""), it has not always been clear what is and isn't allowed by custodians, and what the expectations are. To prevent further unintentional conflicts, document the limited cases where custodians are allowed to modify patches directly, and how to do that.

---
Changes in v3:
- After Quentin's feedback, clarify that only changes suggested by checkpatch.pl are allowed without reposting
- Add references for checkpatch.pl and Signed-off-by Changes in v2:
- New patch.

---
 doc/develop/process.rst | 6 ++++++
 1 file changed, 6 insertions(+)
doc/develop/process.rst +6 -0
index 4159a945707e..0651a1c23a48 100644
@@ -144,6 +144,12 @@ feedback to the submitter of a patch about what is going on:
     feels it has been too long since posting their patch and not
     received any feedback, it is OK to follow-up and ask.
 
+    * A custodian may make changes suggested by :doc:`checkpatch.pl
+      <checkpatch>`. They must also in turn amend the commit message noting
+      their change, for example ``[trini: Fix typos]``, and add their own
+      :ref:`Signed-off-by <dco>` tag. All other changes must be handled by
+      another iteration of the patch, or follow-up patch.
+
   * If the patch itself can still be applied to the tree. The custodian
     is expected to put in a "best effort" if a patch does not apply
     cleanly, but can be made to apply still. It is up to the custodian
Signature · 1 line
2.43.0
Reviewed-by on v3 3/3
#17 lore raw

Re: [PATCH v3 3/3] doc: develop: process: Explain when/how Custodians may edit patches

Hi Tom,

Quoted 7 lines · Tom Rini

As seen with commit d503633a3676 ("Revert "doc: board: starfive: update jh7110 common description""), it has not always been clear what is and isn't allowed by custodians, and what the expectations are. To prevent further unintentional conflicts, document the limited cases where custodians are allowed to modify patches directly, and how to do that.

Thanks!
Quentin