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/ > 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. [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. > +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? > +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 > ++ > + $ 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
Attachment:
signature.asc
Description: PGP signature
