doc: develop: process: Clarify some patch editing expectations
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
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
@@ -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
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.
Signed-off-by Tom Rini <[email protected]>---
Changes in v2:
- New patch.--- doc/develop/process.rst | 22 +++++++++++++--------- 1 file changed, 13 insertions(+), 9 deletions(-)doc/develop/process.rst +0
-0
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
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.
Signed-off-by Tom Rini <[email protected]>---
Changes in v2:
- New patch.--- doc/develop/process.rst | 22 +++++++++++++--------- 1 file changed, 13 insertions(+), 9 deletions(-)doc/develop/process.rst +0
-0doc/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 theThe 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 aUnnecessary 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
PATCH v2 2/3 doc: develop: process: Rework the custodian feedback section
In reply to Tom RiniNow 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
@@ -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
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.
Signed-off-by Tom Rini <[email protected]>---
Changes in v2:
- New patch.--- doc/develop/process.rst | 43 +++++++++++++++++++++-------------------- 1 file changed, 22 insertions(+), 21 deletions(-)doc/develop/process.rst +0
-14@@ -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
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.
Signed-off-by Tom Rini <[email protected]>---
Changes in v2:
- New patch.--- doc/develop/process.rst | 43 +++++++++++++++++++++-------------------- 1 file changed, 22 insertions(+), 21 deletions(-)doc/develop/process.rst +0
-19@@ -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 listFor 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.
Reviewed-by Quentin Schulz <[email protected]>
Thanks.
Signature · 1 line
Tom
PATCH v2 3/3 doc: develop: process: Explain when/how Custodians may edit patches
In reply to Tom RiniAs 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
@@ -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
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.Signed-off-by Tom Rini <[email protected]>---
Changes in v2:
- New patch.--- doc/develop/process.rst | 6 ++++++ 1 file changed, 6 insertions(+)doc/develop/process.rst +0
-0
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
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.Signed-off-by Tom Rini <[email protected]>---
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@@ -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 amendI 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
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.Signed-off-by Tom Rini <[email protected]>---
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@@ -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 amendI 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
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.Signed-off-by Tom Rini <[email protected]>---
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@@ -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 amendI 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
v3 cover doc: develop: process: Clarify some patch editing expectations
In reply to Tom RiniHey 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
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
@@ -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
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.
Signed-off-by Tom Rini <[email protected]>
Thanks!
Quentin
PATCH v3 2/3 doc: develop: process: Rework the custodian feedback section
In reply to Tom RiniNow 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
@@ -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
PATCH v3 3/3 doc: develop: process: Explain when/how Custodians may edit patches
In reply to Tom RiniAs 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
@@ -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
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.Signed-off-by Tom Rini <[email protected]>
Thanks!
Quentin