Patrick Steinhardt <ps@xxxxxx> writes: > On Tue, May 14, 2024 at 02:30:39PM +0200, Karthik Nayak wrote: >> From: Karthik Nayak <karthik.188@xxxxxxxxx> >> >> Add a section to explain how to work around other in-flight patches and >> how to navigate conflicts which arise as a series is being iterated. >> This will provide the necessary steps that users can follow to reduce > > s/This will/This provides/ > Thanks, will change! >> friction with other ongoing topics and also provides guidelines on how >> the users can also communicate this to the list efficiently. >> >> Co-authored-by: Junio C Hamano <gitster@xxxxxxxxx> >> Suggested-by: Junio C Hamano <gitster@xxxxxxxxx> >> Signed-off-by: Karthik Nayak <karthik.188@xxxxxxxxx> >> --- >> >> This came off a discussion wherein I sent a series based on `next` >> instead of merging in conflicts [1]. This is mostly worded by Junio and >> I've just put it together into a patch. >> >> This is based off master, with 'jc/patch-flow-updates' merged in. > > :) > >> >> [1]: https://lore.kernel.org/git/xmqqy18lpoqg.fsf@gitster.g/ >> >> Documentation/SubmittingPatches | 79 +++++++++++++++++++++++++++++++++ >> 1 file changed, 79 insertions(+) >> >> diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches >> index 8332073e27..2fd94dc8de 100644 >> --- a/Documentation/SubmittingPatches >> +++ b/Documentation/SubmittingPatches >> @@ -608,6 +608,85 @@ patch, format it as "multipart/signed", not a text/plain message >> that starts with `-----BEGIN PGP SIGNED MESSAGE-----`. That is >> not a text/plain, it's something else. >> >> +=== Handling Conflicts and Iterating Patches >> + >> +When revising changes made to your patches, it's important to >> +acknowledge the possibility of conflicts with other ongoing topics. To >> +navigate these potential conflicts effectively, follow the recommended >> +steps outlined below: > > Okay. I was first wondering why we only mention conflicts when revising > changes. But I see there are other parts in the document where we > already mention the potential for conflicts, so this is fine. > >> +. Build on a suitable base branch, see the <<choose-starting-point, section above>>, >> +and format-patch the series. If you are doing "rebase -i" in-place to >> +update from the previous round, this will reuse the previous base so >> +(2) and (3) may become trivial. >> + >> +. Find the base of where the last round was queued > > It's somewhat unusual for bulleted lists to start with a dot, but this > is consistent with the remainder of this document. > Yeah, that's mostly why I added dots instead of asterisks here. > > [snip] >> +Do not forget to write in the cover letter you did this, including the >> +topics you have in your base on top of 'master'. Then go to (4). >> + >> +. Make a trial merge of your topic into 'next' and 'seen', e.g. >> ++ >> + $ git checkout --detach 'origin/seen' && >> + $ git revert -m 1 <the merge of the previous iteration into seen> && >> + $ git merge kn/ref-transaction-symref > > Let's remove the trailing '&&' lines. The leading dollar indicates that > this is interactive, so you wouldn't concatenate the commands like this. > Also, preceding code didn't have it. > Yeah, agreed, I will remove here and below >> +The "revert" is needed if the previous iteration of your topic is >> +already in 'seen' (like in this case). You could choose to rebuild >> +master..origin/seen from scratch while excluding your previous >> +iteration, which may emulate what happens on the maintainers end more >> +closely. >> ++ >> +This trial merge may conflict. It is primarily to see what conflicts >> +_other_ topics may have with your topic. In other words, you do not >> +have to depend on to make your topic work on 'master'. It may become > > I think there's either a word too many or missing -- depend on what? > 's/depend on/depend on it/' should do I think. >> +the job of the other topic owners to resolve conflicts if your topic >> +goes to 'next' before theirs. >> ++ >> +Make a note on what conflict you saw in the cover letter. You do not >> +necessarily have to resolve them, but it would be a good opportunity to >> +learn what others are doing in an related area. > > s/an/a > I think it makes sense to make it 's/an related area/related areas/'. >> ++ >> + $ git checkout --detach 'origin/next' && >> + $ git merge kn/ref-transaction-symref > > Same comment here regarding the ampersands. > > Other than that the additions look good to me, thanks! > > Patrick Thanks for the review. Will send a follow up version!
Attachment:
signature.asc
Description: PGP signature
