SubmittingPatches: add section for iterating patches
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 provides the necessary steps that users can follow to reduce 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@pobox.com> Suggested-by: Junio C Hamano <gitster@pobox.com> Signed-off-by: Karthik Nayak <karthik.188@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Karthik Nayak committed
May 17, 2024 at 14:27 UTC
c397ddffc3a79e0111a787ce8f9e643c793dc22a
1 file changed
+79
Documentation/SubmittingPatches
+79
@@ -608,6 +608,85 @@ patch, format it as "multipart/signed", not a text/plain message
608
that starts with `-----BEGIN PGP SIGNED MESSAGE-----`. That is
609
not a text/plain, it's something else.
610
611
+=== Handling Conflicts and Iterating Patches
612
+
613
+When revising changes made to your patches, it's important to
614
+acknowledge the possibility of conflicts with other ongoing topics. To
615
+navigate these potential conflicts effectively, follow the recommended
616
+steps outlined below:
617
+
618
+. Build on a suitable base branch, see the <<choose-starting-point, section above>>,
619
+and format-patch the series. If you are doing "rebase -i" in-place to
620
+update from the previous round, this will reuse the previous base so
621
+(2) and (3) may become trivial.
622
+
623
+. Find the base of where the last round was queued
624
++
625
+ $ mine='kn/ref-transaction-symref'
626
+ $ git checkout "origin/seen^{/^Merge branch '$mine'}...master"
627
+
628
+. Apply your format-patch result. There are two cases
629
+.. Things apply cleanly and tests fine. Go to (4).
630
+.. Things apply cleanly but does not build or test fails, or things do
631
+not apply cleanly.
632
++
633
+In the latter case, you have textual or semantic conflicts coming from
634
+the difference between the old base and the base you used to build in
635
+(1). Identify what caused the breakages (e.g., a topic or two may have
636
+merged since the base used by (2) until the base used by (1)).
637
++
638
+Check out the latest 'origin/master' (which may be newer than the base
639
+used by (2)), "merge --no-ff" the topics you newly depend on in there,
640
+and use the result of the merge(s) as the base, rebuild the series and
641
+test again. Run format-patch from the last such merges to the tip of
642
+your topic. If you did
643
++
644
+ $ git checkout origin/master
645
+ $ git merge --no-ff --into-name kn/ref-transaction-symref fo/obar
646
+ $ git merge --no-ff --into-name kn/ref-transaction-symref ba/zqux
647
+ ... rebuild the topic ...
648
++
649
+Then you'd just format your topic above these "preparing the ground"
650
+merges, e.g.
651
++
652
+ $ git format-patch "HEAD^{/^Merge branch 'ba/zqux'}"..HEAD
653
++
654
+Do not forget to write in the cover letter you did this, including the
655
+topics you have in your base on top of 'master'. Then go to (4).
656
+
657
+. Make a trial merge of your topic into 'next' and 'seen', e.g.
658
++
659
+ $ git checkout --detach 'origin/seen'
660
+ $ git revert -m 1 <the merge of the previous iteration into seen>
661
+ $ git merge kn/ref-transaction-symref
662
++
663
+The "revert" is needed if the previous iteration of your topic is
664
+already in 'seen' (like in this case). You could choose to rebuild
665
+master..origin/seen from scratch while excluding your previous
666
+iteration, which may emulate what happens on the maintainers end more
667
+closely.
668
++
669
+This trial merge may conflict. It is primarily to see what conflicts
670
+_other_ topics may have with your topic. In other words, you do not
671
+have to depend on it to make your topic work on 'master'. It may
672
+become the job of the other topic owners to resolve conflicts if your
673
+topic goes to 'next' before theirs.
674
++
675
+Make a note on what conflict you saw in the cover letter. You do not
676
+necessarily have to resolve them, but it would be a good opportunity to
677
+learn what others are doing in related areas.
678
++
679
+ $ git checkout --detach 'origin/next'
680
+ $ git merge kn/ref-transaction-symref
681
++
682
+This is to see what conflicts your topic has with other topics that are
683
+already cooking. This should not conflict if (3)-2 prepared a base on
684
+top of updated master plus dependent topics taken from 'next'. Unless
685
+the context is severe (one way to tell is try the same trial merge with
686
+your old iteration, which may conflict in a similar way), expect that it
687
+will be handled on maintainers end (if it gets unmanageable, I'll ask to
688
+rebase when I receive your patches).
689
+
690
== Subsystems with dedicated maintainers
691
692
Some parts of the system have dedicated maintainers with their own