{"thread":{"id":"58730","subject":"[PATCH 0/2] Documentation/howto/maintain-git.txt: a pair of bugfixes","startedAt":"2022-10-31T23:47:44Z","lastAt":"2022-11-02T08:01:59Z","messageCount":8,"participants":["Taylor Blau","Jeff King","Junio C Hamano"],"isPatch":true,"patchVersion":1,"patchTotal":2},"messages":[{"id":"466136","messageId":"cover.1667260044.git.me@ttaylorr.com","threadId":"58730","inReplyTo":null,"subject":"[PATCH 0/2] Documentation/howto/maintain-git.txt: a pair of bugfixes","fromName":"Taylor Blau","fromEmail":"me@ttaylorr.com","sentAt":"2022-10-31T23:47:33Z","receivedAt":"2022-10-31T23:47:44Z","isPatch":true,"sender":{"key":"me@ttaylorr.com","avatar":"https://avatars.githubusercontent.com/u/301000140?v=4"},"body":"The documentation on how to use the scripts in 'todo' has a couple of\nsmall typos that make it confusing when generating the Meta/redo-jch.sh\nand Meta/redo-seen.sh scripts the first time.\n\nCorrect these to avoid any confusion in the future.\n\nNote that this branch is based off of 'tb/howto-using-redo-script'.\n\nThanks in advance for your review.\n\nTaylor Blau (2):\n  Documentation: build redo-jch.sh from master..jch\n  Documentation: build redo-seen.sh from jch..seen\n\n Documentation/howto/maintain-git.txt | 9 +++++++--\n 1 file changed, 7 insertions(+), 2 deletions(-)\n\n-- \n2.38.0.16.g393fd4c6db\n"},{"id":"466137","messageId":"7fa56b1a002338cba17013e904ee095813bb772c.1667260044.git.me@ttaylorr.com","threadId":"58730","inReplyTo":"cover.1667260044.git.me@ttaylorr.com","subject":"[PATCH 1/2] Documentation: build redo-jch.sh from master..jch","fromName":"Taylor Blau","fromEmail":"me@ttaylorr.com","sentAt":"2022-10-31T23:47:41Z","receivedAt":"2022-10-31T23:47:46Z","isPatch":true,"sender":{"key":"me@ttaylorr.com","avatar":"https://avatars.githubusercontent.com/u/301000140?v=4"},"body":"Rebuilding the 'jch' branch begins by reintegrating any topics between\n'master' and 'jch', not 'master' and 'seen'.\n\nIn the maintainer guide, the documentation isn't quite right, since the\ninitial input to Meta/Reintegrate is \"master..seen\", not \"master..jch\".\nThis can lead to confusing results when generating the Meta/redo-jch.sh\nscript for the first time.\n\nAdditionally, rebuilding 'jch' takes place in two steps. First, running\nthe script up to the first \"### match next\" cut-line, and then comparing\nthe result with what's on 'next' (i.e. with \"git diff jch next\"). Then,\nthe remaining set of topics get merged down to 'jch' (which aren't on\n'next') by running the entire \"redo-jch.sh\" script.\n\nClarify the documentation to reflect this.\n\nSigned-off-by: Taylor Blau <me@ttaylorr.com>\n---\n Documentation/howto/maintain-git.txt | 7 ++++++-\n 1 file changed, 6 insertions(+), 1 deletion(-)\n\ndiff --git a/Documentation/howto/maintain-git.txt b/Documentation/howto/maintain-git.txt\nindex 215e2edb0f..bac6429fbc 100644\n--- a/Documentation/howto/maintain-git.txt\n+++ b/Documentation/howto/maintain-git.txt\n@@ -231,7 +231,7 @@ by doing the following:\n  - Prepare 'jch' branch, which is used to represent somewhere\n    between 'master' and 'seen' and often is slightly ahead of 'next'.\n \n-     $ Meta/Reintegrate master..seen >Meta/redo-jch.sh\n+     $ Meta/Reintegrate master..jch >Meta/redo-jch.sh\n \n    The result is a script that lists topics to be merged in order to\n    rebuild 'seen' as the input to Meta/Reintegrate script.  Remove\n@@ -283,6 +283,11 @@ by doing the following:\n \n      $ git diff jch next\n \n+   Then build the rest of 'jch':\n+\n+     $ git checkout jch\n+     $ sh Meta/redo-jch.sh\n+\n    When all is well, clean up the redo-jch.sh script with\n \n      $ sh Meta/redo-jch.sh -u\n-- \n2.38.0.16.g393fd4c6db\n\n"},{"id":"466138","messageId":"c805f06b0141f6df1543b7433c20b88028169908.1667260044.git.me@ttaylorr.com","threadId":"58730","inReplyTo":"cover.1667260044.git.me@ttaylorr.com","subject":"[PATCH 2/2] Documentation: build redo-seen.sh from jch..seen","fromName":"Taylor Blau","fromEmail":"me@ttaylorr.com","sentAt":"2022-10-31T23:47:44Z","receivedAt":"2022-10-31T23:47:53Z","isPatch":true,"sender":{"key":"me@ttaylorr.com","avatar":"https://avatars.githubusercontent.com/u/301000140?v=4"},"body":"In a similar spirit as the previous commit, the 'seen' branch gets\nrebuilt by reintegrating topics between 'jch' and the (old) tip of\n'seen'.\n\nUpdate the instructions on how to generate Meta/redo-seen.sh for the\nfirst time to reflect this.\n\nSigned-off-by: Taylor Blau <me@ttaylorr.com>\n---\n Documentation/howto/maintain-git.txt | 2 +-\n 1 file changed, 1 insertion(+), 1 deletion(-)\n\ndiff --git a/Documentation/howto/maintain-git.txt b/Documentation/howto/maintain-git.txt\nindex bac6429fbc..d07c6d44e5 100644\n--- a/Documentation/howto/maintain-git.txt\n+++ b/Documentation/howto/maintain-git.txt\n@@ -298,7 +298,7 @@ by doing the following:\n \n  - Rebuild 'seen'.\n \n-     $ Meta/Reintegrate master..seen >Meta/redo-seen.sh\n+     $ Meta/Reintegrate jch..seen >Meta/redo-seen.sh\n \n    Edit the result by adding new topics that are not still in 'seen'\n    in the script.  Then\n-- \n2.38.0.16.g393fd4c6db\n"},{"id":"466184","messageId":"Y2DSSM8ujceSgp+b@coredump.intra.peff.net","threadId":"58730","inReplyTo":"cover.1667260044.git.me@ttaylorr.com","subject":"Re: [PATCH 0/2] Documentation/howto/maintain-git.txt: a pair of bugfixes","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2022-11-01T08:01:12Z","receivedAt":"2022-11-01T08:01:21Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Mon, Oct 31, 2022 at 07:47:33PM -0400, Taylor Blau wrote:\n\n> The documentation on how to use the scripts in 'todo' has a couple of\n> small typos that make it confusing when generating the Meta/redo-jch.sh\n> and Meta/redo-seen.sh scripts the first time.\n> \n> Correct these to avoid any confusion in the future.\n\nThanks for writing these up. A little back-story: Taylor and I had\nlooked at this together off-list, because the results of following the\ndocumentation to the letter made little sense.\n\nSo both look good to me, with the giant grain of salt that I was party\nto the original head-scratching that led to the patches. Given that\nthere's no urgency (unless you are hit by a bus in the next few weeks),\nit probably makes sense to queue these fixes and wait for Junio to\nreview and (hopefully) merge them.\n\nThere is one thing we wondered about, and I think only Junio can answer.\nThe instructions after these patches yield two files, redo-jch.sh and\nredo-seen.sh. The first one has two sections separated by a \"###\"\nmarker: the ones that are in 'next', and the ones that are in 'jch'.\nThe third ones has topics that are only in 'seen' (which also contains\nall of the others).\n\nWhy not have a single file with all of the topics, with two \"###\"\nmarkers? I.e., something like:\n\n  # build the topic list from what's in 'seen' now\n  Meta/Reintegrate master..seen >Meta/redo.sh\n\n  # rebuild the first part of jch, which is everything in next\n  git checkout -B master jch\n  Meta/redo.sh -c1\n\n  # now build actual next, which should end up with the same tree\n  git checkout next\n  git merge master ;# if necessary\n  Meta/redo.sh -c1 -e ;# -e to annotate any topics\n  git diff jch next ;# should be identical\n\n  # now build the rest of jch\n  git checkout jch\n  Meta/redo.sh -c2\n\n  # now build seen\n  git checkout -B seen master\n  Meta/redo.sh ;# no -c, do it all\n\nI _think_ the two are equivalent, and it seems more convenient to keep\nall of the topic names in one file (since they'd migrate across the cut\nto go from seen to jch, then jch to next). But maybe you (Junio) find it\nmore convenient to keep them separate. The 'seen' list is a bit more\nfluid, and I'm sure you figured out how to copy lines between two\ndifferent buffers in emacs. :)\n\nMostly just curious.\n\n-Peff\n"},{"id":"466220","messageId":"Y2GOdwOcb/GtR0LD@nand.local","threadId":"58730","inReplyTo":"Y2DSSM8ujceSgp+b@coredump.intra.peff.net","subject":"Re: [PATCH 0/2] Documentation/howto/maintain-git.txt: a pair of bugfixes","fromName":"Taylor Blau","fromEmail":"me@ttaylorr.com","sentAt":"2022-11-01T21:24:07Z","receivedAt":"2022-11-01T21:24:15Z","isPatch":true,"sender":{"key":"me@ttaylorr.com","avatar":"https://avatars.githubusercontent.com/u/301000140?v=4"},"body":"On Tue, Nov 01, 2022 at 04:01:12AM -0400, Jeff King wrote:\n> On Mon, Oct 31, 2022 at 07:47:33PM -0400, Taylor Blau wrote:\n>\n> > The documentation on how to use the scripts in 'todo' has a couple of\n> > small typos that make it confusing when generating the Meta/redo-jch.sh\n> > and Meta/redo-seen.sh scripts the first time.\n> >\n> > Correct these to avoid any confusion in the future.\n>\n> Thanks for writing these up. A little back-story: Taylor and I had\n> looked at this together off-list, because the results of following the\n> documentation to the letter made little sense.\n>\n> So both look good to me, with the giant grain of salt that I was party\n> to the original head-scratching that led to the patches. Given that\n> there's no urgency (unless you are hit by a bus in the next few weeks),\n> it probably makes sense to queue these fixes and wait for Junio to\n> review and (hopefully) merge them.\n\nAll true :-).\n\nAnd indeed, if I'm hit by a bus in the next couple of weeks, I think\nthat whoever steps up will be clever enough to find this thread on the\nlist and work it out from there.\n\nLet's hope that we don't have to go there. I'm mainly interested in\nJunio's review, anyway, so I'll happily let this one sit until we hear\nfrom him.\n\n> There is one thing we wondered about, and I think only Junio can answer.\n> The instructions after these patches yield two files, redo-jch.sh and\n> redo-seen.sh. The first one has two sections separated by a \"###\"\n> marker: the ones that are in 'next', and the ones that are in 'jch'.\n> The third ones has topics that are only in 'seen' (which also contains\n> all of the others).\n>\n> Why not have a single file with all of the topics, with two \"###\"\n> markers? I.e., something like:\n\nThanks for writing our confusion up. I, too, think that this would be an\neasier process to follow than juggling the topics between two files. I\ncould imagine that there was some circumstance that bit Junio in the\npast (for which it really *is* easier to manage the set of topics broken\nout across two files).\n\nI could equally imagine the answer being, \"it's always been this way\",\nand so the process is baked into his muscle memory. Whatever the reason\nis, I'm definitely curious in the rationale behind it.\n\n>   # build the topic list from what's in 'seen' now\n>   Meta/Reintegrate master..seen >Meta/redo.sh\n>\n>   # rebuild the first part of jch, which is everything in next\n>   git checkout -B master jch\n>   Meta/redo.sh -c1\n>\n>   # now build actual next, which should end up with the same tree\n>   git checkout next\n>   git merge master ;# if necessary\n>   Meta/redo.sh -c1 -e ;# -e to annotate any topics\n>   git diff jch next ;# should be identical\n>\n>   # now build the rest of jch\n>   git checkout jch\n>   Meta/redo.sh -c2\n>\n>   # now build seen\n>   git checkout -B seen master\n>   Meta/redo.sh ;# no -c, do it all\n>\n> I _think_ the two are equivalent, and it seems more convenient to keep\n> all of the topic names in one file (since they'd migrate across the cut\n> to go from seen to jch, then jch to next). But maybe you (Junio) find it\n> more convenient to keep them separate. The 'seen' list is a bit more\n> fluid, and I'm sure you figured out how to copy lines between two\n> different buffers in emacs. :)\n\nBased on my own understanding of the scripts in 'todo', I agree that\nthey should be equivalent.\n\nThanks,\nTaylor\n"},{"id":"466225","messageId":"xmqqo7tqco0y.fsf@gitster.g","threadId":"58730","inReplyTo":"Y2DSSM8ujceSgp+b@coredump.intra.peff.net","subject":"Re: [PATCH 0/2] Documentation/howto/maintain-git.txt: a pair of bugfixes","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2022-11-01T22:23:25Z","receivedAt":"2022-11-01T22:23:59Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jeff King <peff@peff.net> writes:\n\n> Why not have a single file with all of the topics, with two \"###\"\n> markers?\n\nMostly because jch and seen are built in two distinct steps, and I\nneed to be able to rearrange lines in the redo-jch.sh file either in\nthe editor or by running \"Meta/redo-jch.sh -u\", without touching\nwhat is in redo-seen.sh file (meaning: what comes after your final\n\"###\" cut lines).\n\nAfter replacing the existing topic branches and creating new ones\nfor new topics, decide which topics to merge down to master and next\nand edit redo-jch.sh (while looking at the what's cooking report\nand/or output from \"Meta/cook -w\").  If we merge some to 'master',\nthen tentatively write '###' marker before these topics.  Then\n\n    $ git checkout --detach master\n    $ Meta/redo-jch.sh -c1\n    $ edit RelNotes\n    $ git commit -a -s -m \"${N}th batch\"\n    $ Meta/round -coccinelle ;# and other tests as necessary\n    $ Meta/Reintegrate master.. >P\n    $ git checkout master\n    $ sh P && git commit --amend --no-edit --reset-author\n\nwill rebuild the 'master' (but this is needed only when 'master'\ngets updated in the day's integration).  After that\n\n    $ git checkout -B jch master\n    $ Meta/redo-jch.sh\n\nand use \n\n    $ git branch --no-merged jch --no-merged seen --sort=-committerdate '??/*'\n\nto see any topics that are not in last 'seen' and 'jch' we just\nrebuilt.  They are either replaced in 'seen' or new ones.  Then\nmerge some of them that you are more confident than others to 'jch'\nand test and update the redo-jch.sh script.\n\n    $ git merge xy/xxy\n    $ git merge fr/otz\n    ...\n    $ Meta/round ;# or whatever tests that are appropriate\n    $ Meta/redo-jch.sh -u\n\nThis \"-u\"pdate step can be done without disturbing what should later\nbuild on top for 'seen' by having the script separately.  \n\nWhen day's integration contains an update to 'next', there is\nanother step here:\n\n    $ git checkout --detach next\n    $ Meta/redo-jch.sh -c1\n    $ git merge -m \"Sync with 'master'\" --no-log master\n    $ Meta/round ;# or whatever tests that are appropriate\n    $ git diff 'jch^{/^### match next}' ;# must be empty\n\nAfter that, queue new topics that are more questionable on 'seen',\nand the rest:\n\n    $ git checkotu -B seen\n    $ git merge ni/tfol\n    $ git merge yo/min\n    ...\n    $ Meta/round ;# or whatever tests that are appropriate\n    ... here, new topics may be worse than what I initially thought\n    ... that they need to be ejected from 'seen'\n    $ git reset --hard jch && git merge yo/min ... && Meta/round\n\nAnd once satisfied with the new topics, queue the remainder.\n\n    $ Meta/redo-seen.sh\n    $ Meta/round ;# or whatever tests that are appropriate\n    $ Meta/redo-seen.sh -u ;# finally\n\nBeing able to rebuild the redo-* script for only the 'jch' part,\nindependent from the 'seen' part, is quite essential in the\nworkflow, because I may not yet know how day's 'seen' would look\nlike, when I am recording the topics and integration order for 'jch'.\n"},{"id":"466269","messageId":"Y2GvyyG3K1OpIqAw@nand.local","threadId":"58730","inReplyTo":"xmqqo7tqco0y.fsf@gitster.g","subject":"Re: [PATCH 0/2] Documentation/howto/maintain-git.txt: a pair of bugfixes","fromName":"Taylor Blau","fromEmail":"me@ttaylorr.com","sentAt":"2022-11-01T23:46:19Z","receivedAt":"2022-11-01T23:46:27Z","isPatch":true,"sender":{"key":"me@ttaylorr.com","avatar":"https://avatars.githubusercontent.com/u/301000140?v=4"},"body":"On Tue, Nov 01, 2022 at 03:23:25PM -0700, Junio C Hamano wrote:\n> Jeff King <peff@peff.net> writes:\n>\n> > Why not have a single file with all of the topics, with two \"###\"\n> > markers?\n>\n> Mostly because jch and seen are built in two distinct steps, and I\n> need to be able to rearrange lines in the redo-jch.sh file either in\n> the editor or by running \"Meta/redo-jch.sh -u\", without touching\n> what is in redo-seen.sh file (meaning: what comes after your final\n> \"###\" cut lines).\n\nVery helpful. Thank you :-).\n\nThanks,\nTaylor\n"},{"id":"466293","messageId":"Y2Ij8c9NCdhJkTE8@coredump.intra.peff.net","threadId":"58730","inReplyTo":"xmqqo7tqco0y.fsf@gitster.g","subject":"Re: [PATCH 0/2] Documentation/howto/maintain-git.txt: a pair of bugfixes","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2022-11-02T08:01:53Z","receivedAt":"2022-11-02T08:01:59Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Tue, Nov 01, 2022 at 03:23:25PM -0700, Junio C Hamano wrote:\n\n> and use \n> \n>     $ git branch --no-merged jch --no-merged seen --sort=-committerdate '??/*'\n> \n> to see any topics that are not in last 'seen' and 'jch' we just\n> rebuilt.  They are either replaced in 'seen' or new ones.  Then\n> merge some of them that you are more confident than others to 'jch'\n> and test and update the redo-jch.sh script.\n> \n>     $ git merge xy/xxy\n>     $ git merge fr/otz\n>     ...\n>     $ Meta/round ;# or whatever tests that are appropriate\n>     $ Meta/redo-jch.sh -u\n> \n> This \"-u\"pdate step can be done without disturbing what should later\n> build on top for 'seen' by having the script separately.\n\nAh, OK, this is the part I was missing. I assumed you would write the\nnew topic names into the redo-jch file, then run it to create the merged\nstate (since with rerere, it's easy-ish to reset jch back to master and\njust rebuild to the desired spot).\n\nBut that is inside-out from your workflow, which is to treat topics\nindividually. Updating redo-jch.sh is done by the script and explains\nwhat you did manually, rather than manually updating redo-jch.sh and\nhaving it build automatically. Your way makes much more sense, since you\nget the opportunity to examine the intermediate states more closely.\n\nThanks for explaining!\n\n-Peff\n"}]}