{"thread":{"id":"62218","subject":"Linking topic merges to mailing list threads","startedAt":"2024-09-30T16:21:26Z","lastAt":"2024-10-03T18:44:15Z","messageCount":18,"participants":["Emily Shaffer","Konstantin Ryabitsev","Junio C Hamano","Kristoffer Haugsbakk","Taylor Blau","Eric Wong","Jeff King","Ramsay Jones"],"isPatch":false,"patchVersion":null,"patchTotal":null},"messages":[{"id":"503738","messageId":"CAJoAoZ=4ARuH3aHGe5yC_Xcnou_c396q_ZienYPY7YnEzZcyEg@mail.gmail.com","threadId":"62218","inReplyTo":null,"subject":"Linking topic merges to mailing list threads","fromName":"Emily Shaffer","fromEmail":"nasamuffin@google.com","sentAt":"2024-09-30T16:21:11Z","receivedAt":"2024-09-30T16:21:26Z","isPatch":false,"sender":{"key":"nasamuffin@google.com","avatar":"https://avatars.githubusercontent.com/u/1606826?v=4"},"body":"Hi all,\n\nWe've been wanting to gather metrics on Git's code review process -\nhow long it takes from first contact on list to merge, how many\niterations are needed, time between iterations, etc. One missing link\nis the actual merge time in `next` and `master` - a human can infer\nthe link between the patch and the mailing list thread, but it's more\nchallenging for a script to do it.\n\nWould it be possible to modify the maintainer workflow to include a\nlink to the cover letter as merged in the merge commit message (or the\nlink to the latest iteration of the patch if it's a single-patch\nchange)? What issues could come up with that workflow?\n\nI guess one is that we could move from lore.kernel.org to something\nelse, like we saw the migration from public-inbox.org some years ago.\nBut the Message-ID was preserved between the two archives, so maybe\nit's enough to include the Message-ID in the merge commit? Another is,\nof course, the added burden on the maintainer. But maybe there is some\nscript that is already used that we can modify to make the extra load\nnegligible?\n\n(Or, even better, if anybody else is already successfully measuring\nthese kinds of metrics without such a reference, could you let me know\nhow you're doing it? :) )\n\nThanks,\n - Emily\n"},{"id":"503743","messageId":"20240930-sly-outstanding-boar-c16e9c@lemur","threadId":"62218","inReplyTo":"CAJoAoZ=4ARuH3aHGe5yC_Xcnou_c396q_ZienYPY7YnEzZcyEg@mail.gmail.com","subject":"Re: Linking topic merges to mailing list threads","fromName":"Konstantin Ryabitsev","fromEmail":"konstantin@linuxfoundation.org","sentAt":"2024-09-30T16:57:56Z","receivedAt":"2024-09-30T16:57:58Z","isPatch":false,"sender":{"key":"konstantin@linuxfoundation.org","avatar":"https://gravatar.com/avatar/7cb8827c6de56e1bd2dea16508c6708aa43feed3bf3813bcdacecdf96ceadd79?d=mp&s=160"},"body":"On Mon, Sep 30, 2024 at 09:21:11AM GMT, Emily Shaffer wrote:\n> Hi all,\n> \n> We've been wanting to gather metrics on Git's code review process -\n> how long it takes from first contact on list to merge, how many\n> iterations are needed, time between iterations, etc. One missing link\n> is the actual merge time in `next` and `master` - a human can infer\n> the link between the patch and the mailing list thread, but it's more\n> challenging for a script to do it.\n> \n> Would it be possible to modify the maintainer workflow to include a\n> link to the cover letter as merged in the merge commit message (or the\n> link to the latest iteration of the patch if it's a single-patch\n> change)? What issues could come up with that workflow?\n\nOne of the goals of b4 on the kernel side of things was to promote the use of\ncover letters as merge commit templates, but this requires buy-in from\nmaintainers. It also doesn't really work for single-patch series.\n\nFor example, applying a series with \"b4 shazam -M\" will:\n\n- fetch the series into FETCH_HEAD\n- use the cover letter as the basis for the merge commit message\n- insert the links to the source of the series\n- open up the editor, allowing the maintainer to edit the merge commit message\n\nHere's an example of such merge:\n\nhttps://git.kernel.org/pub/scm/utils/b4/b4.git/commit/?id=b6b73918d94985bb2a017784fc14e013b36b38d0\n\n> I guess one is that we could move from lore.kernel.org to something\n> else, like we saw the migration from public-inbox.org some years ago.\n> But the Message-ID was preserved between the two archives, so maybe\n> it's enough to include the Message-ID in the merge commit?\n\nThis should be sufficient, yes, because you should still be able to find the\norigin thread even if lore.kernel.org is defunct at some point.\n\n> Another is, of course, the added burden on the maintainer. But maybe there\n> is some script that is already used that we can modify to make the extra\n> load negligible?\n\nThere is. :)\n\n> (Or, even better, if anybody else is already successfully measuring\n> these kinds of metrics without such a reference, could you let me know\n> how you're doing it? :) )\n\nOn the kernel side, any time the topic of metrics comes up, it gets\nimmediately bogged down in \"how much tracking is okay and how much is spying\"\nkinds of discussions that have never resulted in anything, really.\n\n-K\n\n"},{"id":"503762","messageId":"xmqqv7yd548i.fsf@gitster.g","threadId":"62218","inReplyTo":"CAJoAoZ=4ARuH3aHGe5yC_Xcnou_c396q_ZienYPY7YnEzZcyEg@mail.gmail.com","subject":"Re: Linking topic merges to mailing list threads","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-09-30T19:30:21Z","receivedAt":"2024-09-30T19:30:23Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Emily Shaffer writes:\n\n> We've been wanting to gather metrics on Git's code review process -\n> how long it takes from first contact on list to merge, how many\n> iterations are needed, time between iterations, etc. One missing link\n> is the actual merge time in `next` and `master` - a human can infer\n> the link between the patch and the mailing list thread, but it's more\n> challenging for a script to do it.\n>\n> Would it be possible to modify the maintainer workflow ...\n\nI suspect that there is no need for any workflow change, as all the\nnecessary information should be available from public sources.\n\nThe first-parent chain from 'next' (or 'master' for that matter)\nalready record when they got merged. From there, C^1..C^2 are\nthe commit objects that were merged. notes/amlog knows where\nthey came from (i.e. their Message-Id). From lore/public-inbox\nyou can find out how the iterations of topics went, as long as\nthe topics are threaded properly (and if not, that would not be\nfixable with any maintainer workflow changes), just like how b4 can\nfigure all of that out.\n\nAhh, nothing officially documents amlog and that is what you are\nmissing. It would be very nice if somebody, preferrably somebody\nother than I, after trying the \"maintainer workflow\" by pretending\nto be a maintainer for a day or two with the new info revealed here,\nupdates the Documentation/howto/maintain-git.txt file with the\ninformation below.\n\nThe script post-appplypatch found in the todo branch is made\navailable as .git/hooks/post-applypatch so that \"git am\" knows to\nrun it after creating a commit out of an e-mailed patch. It\npopulates a mapping from commit object name to \"Message-Id\" of\nindividual patch.\n\n\"git rebase\" knows how to propagate this across rebases because\nI have\n\n [notes] rewriteref = refs/notes/amlog\n\nin the .git/config (which means I have to use rebase not cherry-pick\neven when I am touching a single patch, as cherry-pick does not\npreserve notes by design).\n\nNow I think you should have everything, together with what is\nalready in Documentation/howto/maintain-git.txt, piece them together\nto illustrate the life of a patch series.\n\nAs I do not publish reflog for 'seen', you cannot do \"when was the\ntopic got picked up to 'seen'?\", but as far as I am concerned, it is\nby design. Being in 'seen' does not mean anything other than I\nhappened to have seen it, or saw that somebody indicate interest in\nit.\n\nThanks.\n"},{"id":"503769","messageId":"f4d26c91-6fb6-4c9a-b629-d75b572c39d2@app.fastmail.com","threadId":"62218","inReplyTo":"CAJoAoZ=4ARuH3aHGe5yC_Xcnou_c396q_ZienYPY7YnEzZcyEg@mail.gmail.com","subject":"Re: Linking topic merges to mailing list threads","fromName":"Kristoffer Haugsbakk","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2024-09-30T20:41:59Z","receivedAt":"2024-09-30T20:42:55Z","isPatch":false,"sender":{"key":"kristofferhaugsbakk@fastmail.com","avatar":null},"body":"Like Junio explained refs/notes/amlog is a hidden gem for patch\nprovenance.\n\n> Hi all,\n>\n> We've been wanting to gather metrics on Git's code review process -\n> how long it takes from first contact on list to merge, how many\n> iterations are needed, time between iterations, etc. One missing link\n> is the actual merge time in `next` and `master` - a human can infer\n> the link between the patch and the mailing list thread, but it's more\n> challenging for a script to do it.\n\nIs the starting point the email? I think you could fish out the\nMessage-ID and do a grep inside the notes tree\n\n git grep --fixed-string --name-only \\\n '00a9fe6b7d77c16c9fd6dfe746aacf9068a76942.1726206484.git.ps@pks.im' \\\n refs/notes/amlog --\n\n(the resulting hash will need to be cleaned: fanned directory layout[1])\n\nThen try one commit at a time (because there might be unreachable\ncommits from rewrite operations) using git-when-merged(1):[2]\n\n git when-merged --log 7cd8f1cc6e17af54fb78768c259a615b1ccc0205 next\n git when-merged --log 7cd8f1cc6e17af54fb78768c259a615b1ccc0205 master\n\n† 1: e.g. 7c/d8/f1cc6e17af54fb78768c259a615b1ccc0205\n🔗 2: https://github.com/mhagger/git-when-merged\n\n-- \nKristoffer Haugsbakk\n"},{"id":"503770","messageId":"a4b1da93e16d88323181f8f8444f01d96e09ef45.1727729100.git.me@ttaylorr.com","threadId":"62218","inReplyTo":"xmqqv7yd548i.fsf@gitster.g","subject":"[PATCH] Documentation: mention the amlog in howto/maintain-git.txt","fromName":"Taylor Blau","fromEmail":"me@ttaylorr.com","sentAt":"2024-09-30T20:45:14Z","receivedAt":"2024-09-30T20:45:17Z","isPatch":true,"sender":{"key":"me@ttaylorr.com","avatar":"https://avatars.githubusercontent.com/u/301000140?v=4"},"body":"Part of the maintainer's job is to keep up-to-date and publish the\n'amlog' which stores a mapping between a patch's 'Message-Id' e-mail\nheader and the commit generated by applying said patch.\n\nBut our Documentation/howto/maintain-git.txt does not mention the amlog,\nor the scripts which exist to help the maintainer keep the amlog\nup-to-date.\n\n(This bit me during the first integration round I did as interim\nmaintainer[1] involved a lot of manual clean-up. More recently it has\ncome up as part of a research effort to better understand a patch's\nlifecycle on the list[2].)\n\nAddress this gap by briefly documenting the existence and purpose of the\n'post-applypatch' hook in maintaining the amlog entries.\n\n[1]: https://lore.kernel.org/git/Y19dnb2M+yObnftj@nand.local/\n[2]: https://lore.kernel.org/git/CAJoAoZ=4ARuH3aHGe5yC_Xcnou_c396q_ZienYPY7YnEzZcyEg@mail.gmail.com/\n\nSuggested-by: Junio C Hamano \nSigned-off-by: Taylor Blau \n---\n Documentation/howto/maintain-git.txt | 16 ++++++++++++++++\n 1 file changed, 16 insertions(+)\n\ndiff --git a/Documentation/howto/maintain-git.txt b/Documentation/howto/maintain-git.txt\nindex da31332f11..fd1560327c 100644\n--- a/Documentation/howto/maintain-git.txt\n+++ b/Documentation/howto/maintain-git.txt\n@@ -165,6 +165,22 @@ by doing the following:\n In practice, almost no patch directly goes to 'master' or\n 'maint'.\n \n+ The maintainer is expected to update refs/notes/amlog with a\n+ mapping between the applied commit and the 'Message-Id'\n+ corresponding to the e-mail which carried the patch.\n+\n+ This mapping is created with the aid of the \"post-applypatch\" hook\n+ found in the 'todo' branch. That hook should be installed before\n+ applying patches. It is also helpful to carry forward any relevant\n+ amlog entries when rebasing, so the following config may be useful:\n+\n+ [notes]\n+\trewriteref = refs/notes/amlog\n+\n+ Finally, take care that the amlog entries are pushed out during\n+ integration cycles since external tools and contributors (in\n+ addition to internal scripts) may rely on them.\n+\n - Review the last issue of \"What's cooking\" message, review the\n topics ready for merging (topic->master and topic->maint). Use\n \"Meta/cook -w\" script (where Meta/ contains a checkout of the\n\nbase-commit: 3857aae53f3633b7de63ad640737c657387ae0c6\n-- \n2.46.2.633.gf09c3c1769.dirty\n"},{"id":"503772","messageId":"ff2909b2-3526-4628-bb11-b3a09066a7a6@app.fastmail.com","threadId":"62218","inReplyTo":"a4b1da93e16d88323181f8f8444f01d96e09ef45.1727729100.git.me@ttaylorr.com","subject":"Re: [PATCH] Documentation: mention the amlog in howto/maintain-git.txt","fromName":"Kristoffer Haugsbakk","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2024-09-30T21:06:03Z","receivedAt":"2024-09-30T21:06:25Z","isPatch":true,"sender":{"key":"kristofferhaugsbakk@fastmail.com","avatar":null},"body":"On Mon, Sep 30, 2024, at 22:45, Taylor Blau wrote:\n> Part of the maintainer's job is to keep up-to-date and publish the\n> 'amlog' which stores a mapping between a patch's 'Message-Id' e-mail\n> header and the commit generated by applying said patch.\n>\n> But our Documentation/howto/maintain-git.txt does not mention the amlog,\n> or the scripts which exist to help the maintainer keep the amlog\n> up-to-date.\n>\n> (This bit me during the first integration round I did as interim\n> maintainer[1] involved a lot of manual clean-up. More recently it has\n> come up as part of a research effort to better understand a patch's\n> lifecycle on the list[2].)\n>\n> Address this gap by briefly documenting the existence and purpose of the\n> 'post-applypatch' hook in maintaining the amlog entries.\n>\n> [1]: https://lore.kernel.org/git/Y19dnb2M+yObnftj@nand.local/\n> [2]:\n> https://lore.kernel.org/git/CAJoAoZ=4ARuH3aHGe5yC_Xcnou_c396q_ZienYPY7YnEzZcyEg@mail.gmail.com/\n>\n> Suggested-by: Junio C Hamano \n> Signed-off-by: Taylor Blau \n> ---\n> Documentation/howto/maintain-git.txt | 16 ++++++++++++++++\n> 1 file changed, 16 insertions(+)\n>\n> diff --git a/Documentation/howto/maintain-git.txt\n> b/Documentation/howto/maintain-git.txt\n> index da31332f11..fd1560327c 100644\n> --- a/Documentation/howto/maintain-git.txt\n> +++ b/Documentation/howto/maintain-git.txt\n> @@ -165,6 +165,22 @@ by doing the following:\n> In practice, almost no patch directly goes to 'master' or\n> 'maint'.\n>\n> + The maintainer is expected to update refs/notes/amlog with a\n> + mapping between the applied commit and the 'Message-Id'\n> + corresponding to the e-mail which carried the patch.\n> +\n> + This mapping is created with the aid of the \"post-applypatch\" hook\n> + found in the 'todo' branch. That hook should be installed before\n> + applying patches. It is also helpful to carry forward any relevant\n> + amlog entries when rebasing, so the following config may be useful:\n> +\n> + [notes]\n> +\trewriteref = refs/notes/amlog\n\nNit: `[notes]` is indented with spaces while the next line is indented\nwith a tab. I guess it’s supposed to just be spaces in this context?\n\n> +\n> + Finally, take care that the amlog entries are pushed out during\n> + integration cycles since external tools and contributors (in\n> + addition to internal scripts) may rely on them.\n> +\n> - Review the last issue of \"What's cooking\" message, review the\n> topics ready for merging (topic->master and topic->maint). Use\n> \"Meta/cook -w\" script (where Meta/ contains a checkout of the\n>\n> base-commit: 3857aae53f3633b7de63ad640737c657387ae0c6\n> --\n> 2.46.2.633.gf09c3c1769.dirty\n\nIt might be worth explicitly mentioning the git-cherry-pick(1) footgun\nthat Junio talked about in his email: you have to restrict yourself to\ngit-rebase(1) and `git commit --amend`. Since git-cherry-pick(1)\ndoesn’t care about (respect?) this configuration.\n\nRight now it’s implied of course (“when rebasing”).\n\n-- \nKristoffer Haugsbakk\n\n"},{"id":"503778","messageId":"xmqq8qv84xkg.fsf@gitster.g","threadId":"62218","inReplyTo":"a4b1da93e16d88323181f8f8444f01d96e09ef45.1727729100.git.me@ttaylorr.com","subject":"Re: [PATCH] Documentation: mention the amlog in howto/maintain-git.txt","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-09-30T21:54:23Z","receivedAt":"2024-09-30T21:54:25Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Taylor Blau writes:\n\n> Part of the maintainer's job is to keep up-to-date and publish the\n> 'amlog' which stores a mapping between a patch's 'Message-Id' e-mail\n> header and the commit generated by applying said patch.\n>\n> But our Documentation/howto/maintain-git.txt does not mention the amlog,\n> or the scripts which exist to help the maintainer keep the amlog\n> up-to-date.\n>\n> (This bit me during the first integration round I did as interim\n> maintainer[1] involved a lot of manual clean-up. More recently it has\n> come up as part of a research effort to better understand a patch's\n> lifecycle on the list[2].)\n>\n> Address this gap by briefly documenting the existence and purpose of the\n> 'post-applypatch' hook in maintaining the amlog entries.\n>\n> [1]: https://lore.kernel.org/git/Y19dnb2M+yObnftj@nand.local/\n> [2]: https://lore.kernel.org/git/CAJoAoZ=4ARuH3aHGe5yC_Xcnou_c396q_ZienYPY7YnEzZcyEg@mail.gmail.com/\n>\n> Suggested-by: Junio C Hamano \n> Signed-off-by: Taylor Blau \n> ---\n> Documentation/howto/maintain-git.txt | 16 ++++++++++++++++\n> 1 file changed, 16 insertions(+)\n\nThis addition to the procedure part of the documentation reads good.\n\nWe'd need a matching addition to \"The Policy\" part, to describe the\nmotivation separately. The procedure exists only to realize what\nthe policy gives, and we need something to back up the expectation\n\"to update refs/notes/amlog\" (i.e. because there is this policy).\n\nExistig \"policy\" entries are only about how integration branches are\nmaintained and used, but notes/amlog are solely about the individual\npatches, so we'd need an entirely new section there, I guess.\n\nWhile at it, I notice that there is no mention on where these notes\nare published (the configuration you added to the text is solely\nabout the local repository the maintainer uses).\n\nI just added this change\n\n [remote \"github2\"]\n url = https://github.com/git/git\n fetch = +refs/heads/*:refs/remotes/github2/*\n pushurl = github.com:git/git.git\n push = refs/heads/maint:refs/heads/maint\n push = refs/heads/master:refs/heads/master\n push = refs/heads/next:refs/heads/next\n push = +refs/heads/seen:refs/heads/seen\n+ push = +refs/notes/amlog\n\nto github.com/git/git/ and other publishing repositories. My\nbroken-out repository github.com/gitster/git/ have been pushed\nwith the mirror mode, so there needs no change, but others like\nk.org repositories will start seeing this additional ref when I push\nout today's integration results.\n\nThe \"policy\" part of the change may read like the following.\n\nThanks.\n\n Documentation/howto/maintain-git.txt | 8 ++++++++\n 1 file changed, 8 insertions(+)\n\ndiff --git c/Documentation/howto/maintain-git.txt w/Documentation/howto/maintain-git.txt\nindex da31332f11..9b72d435e6 100644\n--- c/Documentation/howto/maintain-git.txt\n+++ w/Documentation/howto/maintain-git.txt\n@@ -35,6 +35,14 @@ The maintainer's Git time is spent on three activities.\n The Policy\n ----------\n \n+Because most of the lines of code in Git are written by individual\n+contributors, and contributions come in the form of e-mailed patches\n+published on the mailing list, the project maintains a mapping from\n+individual commits to the Message-Id of the e-mail that resulted in\n+the commit, to help tracking the origin of the changes. The notes\n+in \"refs/notes/amlog\" are used for this purpose, and are published\n+along with the broken-out branches to the maintainer's repository.\n+\n The policy on Integration is informally mentioned in \"A Note\n from the maintainer\" message, which is periodically posted to\n the mailing list after each feature release is made:\n"},{"id":"503932","messageId":"5cc8e2bcb88424d8dce526f518282e4b26a1760a.1727881364.git.me@ttaylorr.com","threadId":"62218","inReplyTo":"a4b1da93e16d88323181f8f8444f01d96e09ef45.1727729100.git.me@ttaylorr.com","subject":"[PATCH v2] Documentation: mention the amlog in howto/maintain-git.txt","fromName":"Taylor Blau","fromEmail":"me@ttaylorr.com","sentAt":"2024-10-02T15:03:44Z","receivedAt":"2024-10-02T15:03:47Z","isPatch":true,"sender":{"key":"me@ttaylorr.com","avatar":"https://avatars.githubusercontent.com/u/301000140?v=4"},"body":"Part of the maintainer's job is to keep up-to-date and publish the\n'amlog' which stores a mapping between a patch's 'Message-Id' e-mail\nheader and the commit generated by applying said patch.\n\nBut our Documentation/howto/maintain-git.txt does not mention the amlog,\nor the scripts which exist to help the maintainer keep the amlog\nup-to-date.\n\n(This bit me during the first integration round I did as interim\nmaintainer[1] involved a lot of manual clean-up. More recently it has\ncome up as part of a research effort to better understand a patch's\nlifecycle on the list[2].)\n\nAddress this gap by briefly documenting the existence and purpose of the\n'post-applypatch' hook in maintaining the amlog entries.\n\n[1]: https://lore.kernel.org/git/Y19dnb2M+yObnftj@nand.local/\n[2]: https://lore.kernel.org/git/CAJoAoZ=4ARuH3aHGe5yC_Xcnou_c396q_ZienYPY7YnEzZcyEg@mail.gmail.com/\n\nSuggested-by: Junio C Hamano \nHelped-by: Junio C Hamano \nSigned-off-by: Taylor Blau \n---\nSimilar to v1, but with:\n\n- an added change to \"The Policy\" section written by Junio\n\n- a tab/space fix in the notes.rewriteRef example\n\n- and a mention of the fact that the notes.rewriteRef configuration is\n not read by 'cherry-pick'.\n\n Documentation/howto/maintain-git.txt | 25 +++++++++++++++++++++++++\n 1 file changed, 25 insertions(+)\n\ndiff --git a/Documentation/howto/maintain-git.txt b/Documentation/howto/maintain-git.txt\nindex da31332f11..76d6688d4c 100644\n--- a/Documentation/howto/maintain-git.txt\n+++ b/Documentation/howto/maintain-git.txt\n@@ -122,6 +122,13 @@ Note that before v1.9.0 release, the version numbers used to be\n structured slightly differently. vX.Y.Z were feature releases while\n vX.Y.Z.W were maintenance releases for vX.Y.Z.\n\n+Because most of the lines of code in Git are written by individual\n+contributors, and contributions come in the form of e-mailed patches\n+published on the mailing list, the project maintains a mapping from\n+individual commits to the Message-Id of the e-mail that resulted in\n+the commit, to help tracking the origin of the changes. The notes\n+in \"refs/notes/amlog\" are used for this purpose, and are published\n+along with the broken-out branches to the maintainer's repository.\n\n A Typical Git Day\n -----------------\n@@ -165,6 +172,24 @@ by doing the following:\n In practice, almost no patch directly goes to 'master' or\n 'maint'.\n\n+ The maintainer is expected to update refs/notes/amlog with a\n+ mapping between the applied commit and the 'Message-Id'\n+ corresponding to the e-mail which carried the patch.\n+\n+ This mapping is created with the aid of the \"post-applypatch\" hook\n+ found in the 'todo' branch. That hook should be installed before\n+ applying patches. It is also helpful to carry forward any relevant\n+ amlog entries when rebasing, so the following config may be useful:\n+\n+ [notes]\n+ rewriteRef = refs/notes/amlog\n+\n+ (note that this configuration is not read by 'cherry-pick').\n+\n+ Finally, take care that the amlog entries are pushed out during\n+ integration cycles since external tools and contributors (in\n+ addition to internal scripts) may rely on them.\n+\n - Review the last issue of \"What's cooking\" message, review the\n topics ready for merging (topic->master and topic->maint). Use\n \"Meta/cook -w\" script (where Meta/ contains a checkout of the\n\nRange-diff against v1:\n1: a4b1da93e1 ! 1: 5cc8e2bcb8 Documentation: mention the amlog in howto/maintain-git.txt\n @@ Commit message\n [2]: https://lore.kernel.org/git/CAJoAoZ=4ARuH3aHGe5yC_Xcnou_c396q_ZienYPY7YnEzZcyEg@mail.gmail.com/\n\n Suggested-by: Junio C Hamano \n + Helped-by: Junio C Hamano \n Signed-off-by: Taylor Blau \n\n ## Documentation/howto/maintain-git.txt ##\n +@@ Documentation/howto/maintain-git.txt: Note that before v1.9.0 release, the version numbers used to be\n + structured slightly differently. vX.Y.Z were feature releases while\n + vX.Y.Z.W were maintenance releases for vX.Y.Z.\n +\n ++Because most of the lines of code in Git are written by individual\n ++contributors, and contributions come in the form of e-mailed patches\n ++published on the mailing list, the project maintains a mapping from\n ++individual commits to the Message-Id of the e-mail that resulted in\n ++the commit, to help tracking the origin of the changes. The notes\n ++in \"refs/notes/amlog\" are used for this purpose, and are published\n ++along with the broken-out branches to the maintainer's repository.\n +\n + A Typical Git Day\n + -----------------\n @@ Documentation/howto/maintain-git.txt: by doing the following:\n In practice, almost no patch directly goes to 'master' or\n 'maint'.\n @@ Documentation/howto/maintain-git.txt: by doing the following:\n + amlog entries when rebasing, so the following config may be useful:\n +\n + [notes]\n -+\trewriteref = refs/notes/amlog\n ++ rewriteRef = refs/notes/amlog\n ++\n ++ (note that this configuration is not read by 'cherry-pick').\n +\n + Finally, take care that the amlog entries are pushed out during\n + integration cycles since external tools and contributors (in\n\nbase-commit: 3857aae53f3633b7de63ad640737c657387ae0c6\n--\n2.47.0.rc0.4.gd73fb26592.dirty\n"},{"id":"503933","messageId":"Zv1g/dKlLJ2FoEvG@nand.local","threadId":"62218","inReplyTo":"ff2909b2-3526-4628-bb11-b3a09066a7a6@app.fastmail.com","subject":"Re: [PATCH] Documentation: mention the amlog in howto/maintain-git.txt","fromName":"Taylor Blau","fromEmail":"me@ttaylorr.com","sentAt":"2024-10-02T15:04:29Z","receivedAt":"2024-10-02T15:04:31Z","isPatch":true,"sender":{"key":"me@ttaylorr.com","avatar":"https://avatars.githubusercontent.com/u/301000140?v=4"},"body":"On Mon, Sep 30, 2024 at 11:06:03PM +0200, Kristoffer Haugsbakk wrote:\n> > @@ -165,6 +165,22 @@ by doing the following:\n> > In practice, almost no patch directly goes to 'master' or\n> > 'maint'.\n> >\n> > + The maintainer is expected to update refs/notes/amlog with a\n> > + mapping between the applied commit and the 'Message-Id'\n> > + corresponding to the e-mail which carried the patch.\n> > +\n> > + This mapping is created with the aid of the \"post-applypatch\" hook\n> > + found in the 'todo' branch. That hook should be installed before\n> > + applying patches. It is also helpful to carry forward any relevant\n> > + amlog entries when rebasing, so the following config may be useful:\n> > +\n> > + [notes]\n> > +\trewriteref = refs/notes/amlog\n>\n> Nit: `[notes]` is indented with spaces while the next line is indented\n> with a tab. I guess it’s supposed to just be spaces in this context?\n\nOops, good catch, thanks.\n\n> It might be worth explicitly mentioning the git-cherry-pick(1) footgun\n> that Junio talked about in his email: you have to restrict yourself to\n> git-rebase(1) and `git commit --amend`. Since git-cherry-pick(1)\n> doesn’t care about (respect?) this configuration.\n\nI think that's worth mentioning, and I added a small tidbit in the\nlatest round mentioning it, thanks.\n\nThanks,\nTaylor\n"},{"id":"503934","messageId":"Zv1hRnLO9TrIdd1O@nand.local","threadId":"62218","inReplyTo":"xmqq8qv84xkg.fsf@gitster.g","subject":"Re: [PATCH] Documentation: mention the amlog in howto/maintain-git.txt","fromName":"Taylor Blau","fromEmail":"me@ttaylorr.com","sentAt":"2024-10-02T15:05:42Z","receivedAt":"2024-10-02T15:05:45Z","isPatch":true,"sender":{"key":"me@ttaylorr.com","avatar":"https://avatars.githubusercontent.com/u/301000140?v=4"},"body":"On Mon, Sep 30, 2024 at 02:54:23PM -0700, Junio C Hamano wrote:\n> The \"policy\" part of the change may read like the following.\n>\n> Thanks.\n>\n> Documentation/howto/maintain-git.txt | 8 ++++++++\n> 1 file changed, 8 insertions(+)\n>\n> diff --git c/Documentation/howto/maintain-git.txt w/Documentation/howto/maintain-git.txt\n> index da31332f11..9b72d435e6 100644\n> --- c/Documentation/howto/maintain-git.txt\n> +++ w/Documentation/howto/maintain-git.txt\n> @@ -35,6 +35,14 @@ The maintainer's Git time is spent on three activities.\n> The Policy\n> ----------\n>\n> +Because most of the lines of code in Git are written by individual\n> +contributors, and contributions come in the form of e-mailed patches\n> +published on the mailing list, the project maintains a mapping from\n> +individual commits to the Message-Id of the e-mail that resulted in\n> +the commit, to help tracking the origin of the changes. The notes\n> +in \"refs/notes/amlog\" are used for this purpose, and are published\n> +along with the broken-out branches to the maintainer's repository.\n> +\n> The policy on Integration is informally mentioned in \"A Note\n> from the maintainer\" message, which is periodically posted to\n> the mailing list after each feature release is made:\n\nThanks, this looks good to me, and I added it in the latest version of\nthis patch, with your Helped-by.\n\nI moved this section to the end of the this section, not the beginning,\nsince it seems more important to first discuss the mechanics of topic\nbranches, next, seen, master, etc., before getting to the nuts and bolts\nof the amlog ;-).\n\nThanks,\nTaylor\n"},{"id":"503973","messageId":"xmqq8qv6l226.fsf@gitster.g","threadId":"62218","inReplyTo":"5cc8e2bcb88424d8dce526f518282e4b26a1760a.1727881364.git.me@ttaylorr.com","subject":"Re: [PATCH v2] Documentation: mention the amlog in howto/maintain-git.txt","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-10-02T19:47:29Z","receivedAt":"2024-10-02T19:47:31Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Taylor Blau writes:\n\nNow the policy explains what is done (i.e. amlog gives a mapping)\nand for what purpose (i.e. we want to be able to go back to the\norigin), \"... is expected to\" in the actual procedure is redundant.\nIn other words, the procedure section can focus on what is done\nwithout repeating why.\n\n> + The maintainer is expected to update refs/notes/amlog with a\n> + mapping between the applied commit and the 'Message-Id'\n> + corresponding to the e-mail which carried the patch.\n\nI'd replace the above with something like:\n\n Applying the e-mailed patches using \"git am\" automatically\n records the mappings from Message-Id to resulting commit in\n the \"amlog\" note. Periodically check that this is working\n with \"git show -s --notes=amlog $commit\".\n\n> + This mapping is created with the aid of the \"post-applypatch\" hook\n\n\"created\" -> \"maintained\".\n\n> + found in the 'todo' branch. That hook should be installed before\n> + applying patches. It is also helpful to carry forward any relevant\n> + amlog entries when rebasing, so the following config may be useful:\n> +\n> + [notes]\n> + rewriteRef = refs/notes/amlog\n> +\n> + (note that this configuration is not read by 'cherry-pick').\n\n\"(note ...)\" ->\n\n Avoid \"cherry-pick\", as it does not propagate notes by design.\n Use either \"git commit --amend\" or \"git rebase\" to make\n corrections to an existing commit, even for a single-patch\n topic.\n\n> + Finally, take care that the amlog entries are pushed out during\n> + integration cycles since external tools and contributors (in\n> + addition to internal scripts) may rely on them.\n\nThe purpose of pushing amlog out does not need to be repeated here\nin the procedure section.\n\t\n Make sure that push refspec for refs/notes/amlog is in the\n remote configuration for publishing repositories. A few\n sample .git/config entries may look like this:\n\n [remote \"github2\"]\n url = https://github.com/git/git\n fetch = +refs/heads/*:refs/remotes/github2/*\n pushurl = github.com:git/git.git\n push = refs/heads/maint:refs/heads/maint\n push = refs/heads/master:refs/heads/master\n push = refs/heads/next:refs/heads/next\n push = +refs/heads/seen:refs/heads/seen\n push = +refs/notes/amlog\n\n [remote \"github\"]\n url = https://github.com/gitster/git\n pushurl = github.com:gitster/git.git\n mirror\n\nOther than that, nicely done.\n\nThanks for filling the gap in the documentation.\n"},{"id":"504000","messageId":"20241002225057.M796260@dcvr","threadId":"62218","inReplyTo":"CAJoAoZ=4ARuH3aHGe5yC_Xcnou_c396q_ZienYPY7YnEzZcyEg@mail.gmail.com","subject":"Re: Linking topic merges to mailing list threads","fromName":"Eric Wong","fromEmail":"e@80x24.org","sentAt":"2024-10-02T22:50:57Z","receivedAt":"2024-10-02T22:58:58Z","isPatch":false,"sender":{"key":"e@80x24.org","avatar":null},"body":"Emily Shaffer wrote:\n> Hi all,\n> \n> We've been wanting to gather metrics on Git's code review process -\n> how long it takes from first contact on list to merge, how many\n> iterations are needed, time between iterations, etc. One missing link\n> is the actual merge time in `next` and `master` - a human can infer\n> the link between the patch and the mailing list thread, but it's more\n> challenging for a script to do it.\n\nSearching by commit titles as a phrase against email subject (`s:')\ncan probably make it easy w/o having to look up amlog or explicitly\nkeep track of human-unmemorizable metadata such as Message-IDs.\n\nExample:\nhttps://80x24.org/lore/pub/scm/git/git.git/365529e1ea19b44a7a253b780f3ae3a1cb2f081f/s/#merged\n\n...In the \"find merged patch emails\" textarea. Yeah it's part of a\n100% JS-free alternative to cgit, gitweb, etc...\n\n(https://public-inbox.org/meta/20241002223902.4139389-4-e@80x24.org/\n implements the query generation)\n"},{"id":"504002","messageId":"20241002233436.GA3455554@coredump.intra.peff.net","threadId":"62218","inReplyTo":"20241002225057.M796260@dcvr","subject":"Re: Linking topic merges to mailing list threads","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2024-10-02T23:34:36Z","receivedAt":"2024-10-02T23:34:38Z","isPatch":false,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Wed, Oct 02, 2024 at 10:50:57PM +0000, Eric Wong wrote:\n\n> Emily Shaffer wrote:\n> > Hi all,\n> > \n> > We've been wanting to gather metrics on Git's code review process -\n> > how long it takes from first contact on list to merge, how many\n> > iterations are needed, time between iterations, etc. One missing link\n> > is the actual merge time in `next` and `master` - a human can infer\n> > the link between the patch and the mailing list thread, but it's more\n> > challenging for a script to do it.\n> \n> Searching by commit titles as a phrase against email subject (`s:')\n> can probably make it easy w/o having to look up amlog or explicitly\n> keep track of human-unmemorizable metadata such as Message-IDs.\n\nI do that a lot myself, but it sometimes get tripped up when people put\npatches inline, like:\n\n > blah blah blah\n\n Yes, good idea. Maybe like this:\n\n -- >8 --\n foo: frobnicate the bar\n\n Etc...\n\nIn that case you have to do an actual body search. I usually find these\nwith phrase searches in the body text (I'm usually using notmuch, not\npublic-inbox, but I think the same would be true). Of course it may also\nfind more false positives, but usually they're from the same thread\nanyway.\n\nVery occasionally somebody posts a patch snippet and Junio writes a\ncommit message that never even hits the list, but that's pretty rare\nthese days. :)\n\n-Peff\n"},{"id":"504010","messageId":"Zv3u0bx0QqG6q2A2@nand.local","threadId":"62218","inReplyTo":"xmqq8qv6l226.fsf@gitster.g","subject":"Re: [PATCH v2] Documentation: mention the amlog in howto/maintain-git.txt","fromName":"Taylor Blau","fromEmail":"me@ttaylorr.com","sentAt":"2024-10-03T01:09:37Z","receivedAt":"2024-10-03T01:09:39Z","isPatch":true,"sender":{"key":"me@ttaylorr.com","avatar":"https://avatars.githubusercontent.com/u/301000140?v=4"},"body":"On Wed, Oct 02, 2024 at 12:47:29PM -0700, Junio C Hamano wrote:\n> Other than that, nicely done.\n\nAll very fair suggestions. A v3 is on its way...\n\nThanks,\nTaylor\n"},{"id":"504011","messageId":"88a13b9f2b6e7fbed517a7e268e4e371d84a9a10.1727917792.git.me@ttaylorr.com","threadId":"62218","inReplyTo":"a4b1da93e16d88323181f8f8444f01d96e09ef45.1727729100.git.me@ttaylorr.com","subject":"[PATCH v3] Documentation: mention the amlog in howto/maintain-git.txt","fromName":"Taylor Blau","fromEmail":"me@ttaylorr.com","sentAt":"2024-10-03T01:09:56Z","receivedAt":"2024-10-03T01:09:58Z","isPatch":true,"sender":{"key":"me@ttaylorr.com","avatar":"https://avatars.githubusercontent.com/u/301000140?v=4"},"body":"Part of the maintainer's job is to keep up-to-date and publish the\n'amlog' which stores a mapping between a patch's 'Message-Id' e-mail\nheader and the commit generated by applying said patch.\n\nBut our Documentation/howto/maintain-git.txt does not mention the amlog,\nor the scripts which exist to help the maintainer keep the amlog\nup-to-date.\n\n(This bit me during the first integration round I did as interim\nmaintainer[1] involved a lot of manual clean-up. More recently it has\ncome up as part of a research effort to better understand a patch's\nlifecycle on the list[2].)\n\nAddress this gap by briefly documenting the existence and purpose of the\n'post-applypatch' hook in maintaining the amlog entries.\n\n[1]: https://lore.kernel.org/git/Y19dnb2M+yObnftj@nand.local/\n[2]: https://lore.kernel.org/git/CAJoAoZ=4ARuH3aHGe5yC_Xcnou_c396q_ZienYPY7YnEzZcyEg@mail.gmail.com/\n\nSuggested-by: Junio C Hamano \nHelped-by: Junio C Hamano \nSigned-off-by: Taylor Blau \n---\n Documentation/howto/maintain-git.txt | 44 ++++++++++++++++++++++++++++\n 1 file changed, 44 insertions(+)\n\ndiff --git a/Documentation/howto/maintain-git.txt b/Documentation/howto/maintain-git.txt\nindex da31332f113..f52f32eda93 100644\n--- a/Documentation/howto/maintain-git.txt\n+++ b/Documentation/howto/maintain-git.txt\n@@ -122,6 +122,13 @@ Note that before v1.9.0 release, the version numbers used to be\n structured slightly differently. vX.Y.Z were feature releases while\n vX.Y.Z.W were maintenance releases for vX.Y.Z.\n \n+Because most of the lines of code in Git are written by individual\n+contributors, and contributions come in the form of e-mailed patches\n+published on the mailing list, the project maintains a mapping from\n+individual commits to the Message-Id of the e-mail that resulted in\n+the commit, to help tracking the origin of the changes. The notes\n+in \"refs/notes/amlog\" are used for this purpose, and are published\n+along with the broken-out branches to the maintainer's repository.\n \n A Typical Git Day\n -----------------\n@@ -165,6 +172,43 @@ by doing the following:\n In practice, almost no patch directly goes to 'master' or\n 'maint'.\n \n+ Applying the e-mailed patches using \"git am\" automatically records\n+ the mappings from 'Message-Id' to the applied commit in the \"amlog\"\n+ notes. Periodically check that this is working with \"git show -s\n+ --notes=amlog $commit\".\n+\n+ This mapping is maintained with the aid of the \"post-applypatch\"\n+ hook found in the 'todo' branch. That hook should be installed\n+ before applying patches. It is also helpful to carry forward any\n+ relevant amlog entries when rebasing, so the following config may\n+ be useful:\n+\n+ [notes]\n+ rewriteRef = refs/notes/amlog\n+\n+ Avoid \"cherry-pick\", as it does not propagate notes by design. Use\n+ either \"git commit --amend\" or \"git rebase\" to make corrections to\n+ an existing commit, even for a single-patch topic.\n+\n+ Make sure that a push refspec for 'refs/notes/amlog' is in the\n+ remote configuration for publishing repositories. A few sample\n+ configurations look like the following:\n+\n+ [remote \"github\"]\n+ url = https://github.com/gitster/git\n+ pushurl = github.com:gitster/git.git\n+ mirror\n+\n+ [remote \"github2\"]\n+ url = https://github.com/git/git\n+ fetch = +refs/heads/*:refs/remotes/github2/*\n+ pushurl = github.com:git/git.git\n+ push = refs/heads/maint:refs/heads/maint\n+ push = refs/heads/master:refs/heads/master\n+ push = refs/notes/next:refs/notes/next\n+ push = +refs/heads/seen:refs/heads/seen\n+ push = +refs/notes/amlog\n+\n - Review the last issue of \"What's cooking\" message, review the\n topics ready for merging (topic->master and topic->maint). Use\n \"Meta/cook -w\" script (where Meta/ contains a checkout of the\n\nRange-diff against v2:\n1: 5cc8e2bcb88 ! 1: 88a13b9f2b6 Documentation: mention the amlog in howto/maintain-git.txt\n @@ Documentation/howto/maintain-git.txt: by doing the following:\n In practice, almost no patch directly goes to 'master' or\n 'maint'.\n \n -+ The maintainer is expected to update refs/notes/amlog with a\n -+ mapping between the applied commit and the 'Message-Id'\n -+ corresponding to the e-mail which carried the patch.\n ++ Applying the e-mailed patches using \"git am\" automatically records\n ++ the mappings from 'Message-Id' to the applied commit in the \"amlog\"\n ++ notes. Periodically check that this is working with \"git show -s\n ++ --notes=amlog $commit\".\n +\n -+ This mapping is created with the aid of the \"post-applypatch\" hook\n -+ found in the 'todo' branch. That hook should be installed before\n -+ applying patches. It is also helpful to carry forward any relevant\n -+ amlog entries when rebasing, so the following config may be useful:\n ++ This mapping is maintained with the aid of the \"post-applypatch\"\n ++ hook found in the 'todo' branch. That hook should be installed\n ++ before applying patches. It is also helpful to carry forward any\n ++ relevant amlog entries when rebasing, so the following config may\n ++ be useful:\n +\n + [notes]\n + rewriteRef = refs/notes/amlog\n +\n -+ (note that this configuration is not read by 'cherry-pick').\n ++ Avoid \"cherry-pick\", as it does not propagate notes by design. Use\n ++ either \"git commit --amend\" or \"git rebase\" to make corrections to\n ++ an existing commit, even for a single-patch topic.\n +\n -+ Finally, take care that the amlog entries are pushed out during\n -+ integration cycles since external tools and contributors (in\n -+ addition to internal scripts) may rely on them.\n ++ Make sure that a push refspec for 'refs/notes/amlog' is in the\n ++ remote configuration for publishing repositories. A few sample\n ++ configurations look like the following:\n ++\n ++ [remote \"github\"]\n ++ url = https://github.com/gitster/git\n ++ pushurl = github.com:gitster/git.git\n ++ mirror\n ++\n ++ [remote \"github2\"]\n ++ url = https://github.com/git/git\n ++ fetch = +refs/heads/*:refs/remotes/github2/*\n ++ pushurl = github.com:git/git.git\n ++ push = refs/heads/maint:refs/heads/maint\n ++ push = refs/heads/master:refs/heads/master\n ++ push = refs/notes/next:refs/notes/next\n ++ push = +refs/heads/seen:refs/heads/seen\n ++ push = +refs/notes/amlog\n +\n - Review the last issue of \"What's cooking\" message, review the\n topics ready for merging (topic->master and topic->maint). Use\n\nbase-commit: 3857aae53f3633b7de63ad640737c657387ae0c6\n-- \n2.47.0.rc0.8.g9a975e77790\n"},{"id":"504032","messageId":"xmqqo741hzh3.fsf@gitster.g","threadId":"62218","inReplyTo":"88a13b9f2b6e7fbed517a7e268e4e371d84a9a10.1727917792.git.me@ttaylorr.com","subject":"Re: [PATCH v3] Documentation: mention the amlog in howto/maintain-git.txt","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-10-03T17:23:52Z","receivedAt":"2024-10-03T17:23:54Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Taylor Blau writes:\n\n> (This bit me during the first integration round I did as interim\n> maintainer[1] involved a lot of manual clean-up. More recently it has\n> come up as part of a research effort to better understand a patch's\n> lifecycle on the list[2].)\n\nThanks.\n\n"},{"id":"504039","messageId":"14497a9c-8683-440e-b179-2b10b4516d9c@ramsayjones.plus.com","threadId":"62218","inReplyTo":"88a13b9f2b6e7fbed517a7e268e4e371d84a9a10.1727917792.git.me@ttaylorr.com","subject":"Re: [PATCH v3] Documentation: mention the amlog in howto/maintain-git.txt","fromName":"Ramsay Jones","fromEmail":"ramsay@ramsayjones.plus.com","sentAt":"2024-10-03T18:32:04Z","receivedAt":"2024-10-03T18:35:17Z","isPatch":true,"sender":{"key":"ramsay@ramsayjones.plus.com","avatar":"https://avatars.githubusercontent.com/u/33702710?v=4"},"body":"\n\nOn 03/10/2024 02:09, Taylor Blau wrote:\n> Part of the maintainer's job is to keep up-to-date and publish the\n> 'amlog' which stores a mapping between a patch's 'Message-Id' e-mail\n> header and the commit generated by applying said patch.\n> \n> But our Documentation/howto/maintain-git.txt does not mention the amlog,\n> or the scripts which exist to help the maintainer keep the amlog\n> up-to-date.\n> \n> (This bit me during the first integration round I did as interim\n> maintainer[1] involved a lot of manual clean-up. More recently it has\n> come up as part of a research effort to better understand a patch's\n> lifecycle on the list[2].)\n> \n> Address this gap by briefly documenting the existence and purpose of the\n> 'post-applypatch' hook in maintaining the amlog entries.\n> \n> [1]: https://lore.kernel.org/git/Y19dnb2M+yObnftj@nand.local/\n> [2]: https://lore.kernel.org/git/CAJoAoZ=4ARuH3aHGe5yC_Xcnou_c396q_ZienYPY7YnEzZcyEg@mail.gmail.com/\n> \n> Suggested-by: Junio C Hamano \n> Helped-by: Junio C Hamano \n> Signed-off-by: Taylor Blau \n> ---\n> Documentation/howto/maintain-git.txt | 44 ++++++++++++++++++++++++++++\n> 1 file changed, 44 insertions(+)\n> \n> diff --git a/Documentation/howto/maintain-git.txt b/Documentation/howto/maintain-git.txt\n> index da31332f113..f52f32eda93 100644\n> --- a/Documentation/howto/maintain-git.txt\n> +++ b/Documentation/howto/maintain-git.txt\n> @@ -122,6 +122,13 @@ Note that before v1.9.0 release, the version numbers used to be\n> structured slightly differently. vX.Y.Z were feature releases while\n> vX.Y.Z.W were maintenance releases for vX.Y.Z.\n> \n> +Because most of the lines of code in Git are written by individual\n> +contributors, and contributions come in the form of e-mailed patches\n> +published on the mailing list, the project maintains a mapping from\n> +individual commits to the Message-Id of the e-mail that resulted in\n> +the commit, to help tracking the origin of the changes. The notes\n> +in \"refs/notes/amlog\" are used for this purpose, and are published\n> +along with the broken-out branches to the maintainer's repository.\n> \n> A Typical Git Day\n> -----------------\n> @@ -165,6 +172,43 @@ by doing the following:\n> In practice, almost no patch directly goes to 'master' or\n> 'maint'.\n> \n> + Applying the e-mailed patches using \"git am\" automatically records\n> + the mappings from 'Message-Id' to the applied commit in the \"amlog\"\n> + notes. Periodically check that this is working with \"git show -s\n> + --notes=amlog $commit\".\n> +\n> + This mapping is maintained with the aid of the \"post-applypatch\"\n> + hook found in the 'todo' branch. That hook should be installed\n> + before applying patches. It is also helpful to carry forward any\n> + relevant amlog entries when rebasing, so the following config may\n> + be useful:\n> +\n> + [notes]\n> + rewriteRef = refs/notes/amlog\n> +\n> + Avoid \"cherry-pick\", as it does not propagate notes by design. Use\n> + either \"git commit --amend\" or \"git rebase\" to make corrections to\n> + an existing commit, even for a single-patch topic.\n> +\n> + Make sure that a push refspec for 'refs/notes/amlog' is in the\n> + remote configuration for publishing repositories. A few sample\n> + configurations look like the following:\n> +\n> + [remote \"github\"]\n> + url = https://github.com/gitster/git\n> + pushurl = github.com:gitster/git.git\n> + mirror\n> +\n> + [remote \"github2\"]\n> + url = https://github.com/git/git\n> + fetch = +refs/heads/*:refs/remotes/github2/*\n> + pushurl = github.com:git/git.git\n> + push = refs/heads/maint:refs/heads/maint\n> + push = refs/heads/master:refs/heads/master\n> + push = refs/notes/next:refs/notes/next\n\nHmm, s/notes/heads/g perhaps?\n\n> + push = +refs/heads/seen:refs/heads/seen\n> + push = +refs/notes/amlog\n> +\n> - Review the last issue of \"What's cooking\" message, review the\n> topics ready for merging (topic->master and topic->maint). Use\n> \"Meta/cook -w\" script (where Meta/ contains a checkout of the\n> \n\nATB,\nRamsay Jones\n\n\n"},{"id":"504040","messageId":"Zv7l/Fw5gdkWlDxw@nand.local","threadId":"62218","inReplyTo":"14497a9c-8683-440e-b179-2b10b4516d9c@ramsayjones.plus.com","subject":"Re: [PATCH v3] Documentation: mention the amlog in howto/maintain-git.txt","fromName":"Taylor Blau","fromEmail":"me@ttaylorr.com","sentAt":"2024-10-03T18:44:12Z","receivedAt":"2024-10-03T18:44:15Z","isPatch":true,"sender":{"key":"me@ttaylorr.com","avatar":"https://avatars.githubusercontent.com/u/301000140?v=4"},"body":"On Thu, Oct 03, 2024 at 07:32:04PM +0100, Ramsay Jones wrote:\n> > + [remote \"github2\"]\n> > + url = https://github.com/git/git\n> > + fetch = +refs/heads/*:refs/remotes/github2/*\n> > + pushurl = github.com:git/git.git\n> > + push = refs/heads/maint:refs/heads/maint\n> > + push = refs/heads/master:refs/heads/master\n> > + push = refs/notes/next:refs/notes/next\n>\n> Hmm, s/notes/heads/g perhaps?\n\nUgh, serves me right for trying to send this out late my time last\nnight.\n\nPerhaps Junio can tweak this when applying? Otherwise I can send out a\nnew version.\n\nThanks,\nTaylor\n"}]}