{"thread":{"id":"56719","subject":"[PATCH v2] Documentation: specify base point when generating MyFirstContribution patchset","startedAt":"2021-10-15T12:25:45Z","lastAt":"2021-10-16T05:16:40Z","messageCount":4,"participants":["Bagas Sanjaya","Glen Choo","Junio C Hamano"],"isPatch":true,"patchVersion":2,"patchTotal":null},"messages":[{"id":"438839","messageId":"20211015122515.47535-1-bagasdotme@gmail.com","threadId":"56719","inReplyTo":null,"subject":"[PATCH v2] Documentation: specify base point when generating MyFirstContribution patchset","fromName":"Bagas Sanjaya","fromEmail":"bagasdotme@gmail.com","sentAt":"2021-10-15T12:25:16Z","receivedAt":"2021-10-15T12:25:45Z","isPatch":true,"sender":{"key":"bagasdotme@gmail.com","avatar":"https://avatars.githubusercontent.com/u/40219486?v=4"},"body":"Specifying base point (commit hash) can help reviewers and testers\ninterested on the patchset. Mention how to record it with `--base`\noption to `format-patch`.\n\nSigned-off-by: Bagas Sanjaya <bagasdotme@gmail.com>\n---\n Changes since v1 [1]:\n     - Rewording (suggested by Junio).\n     - Show command to determine base commit hash and pass it to `--base`\n       option.\n\n [1]:\nhttps://lore.kernel.org/git/f25fae40-0313-287b-5482-1c64cbe8cb64@gmail.com/T/#t\n\n Documentation/MyFirstContribution.txt | 17 +++++++++++++++++\n 1 file changed, 17 insertions(+)\n\ndiff --git a/Documentation/MyFirstContribution.txt b/Documentation/MyFirstContribution.txt\nindex b20bc8e914..5aaf31cb66 100644\n--- a/Documentation/MyFirstContribution.txt\n+++ b/Documentation/MyFirstContribution.txt\n@@ -937,6 +937,23 @@ but want reviewers to look at what they have so far. You can add this flag with\n Check and make sure that your patches and cover letter template exist in the\n directory you specified - you're nearly ready to send out your review!\n \n+It would help those who review and test your patches to specify on what\n+commit the patches should be applied to. To do so, use the `--base` option\n+when running `format-patch`. The option expects hash of the commit the\n+patchset is based on. Since we base `psuh` on top of `master`, the base\n+commit hash can be determined by: \n+\n+----\n+$ git show -s --format=\"%H\" master\n+----\n+\n+The output of command above can be passed to `--base` option. Replace `<base>`\n+with your own hash:\n+\n+----\n+$ git format-patch --cover-letter --base=<base> -o psuh/ master..psuh\n+----\n+\n [[cover-letter]]\n === Preparing Email\n \n\nbase-commit: 2bd2f258f4195ac54293a3f45b86457c0bd5fc11\n-- \nAn old man doll... just what I always wanted! - Clara\n\n"},{"id":"438877","messageId":"kl6l4k9i1ame.fsf@chooglen-macbookpro.roam.corp.google.com","threadId":"56719","inReplyTo":"20211015122515.47535-1-bagasdotme@gmail.com","subject":"Re: [PATCH v2] Documentation: specify base point when generating MyFirstContribution patchset","fromName":"Glen Choo","fromEmail":"chooglen@google.com","sentAt":"2021-10-15T17:06:01Z","receivedAt":"2021-10-15T17:06:10Z","isPatch":true,"sender":{"key":"glencbz@gmail.com","avatar":"https://avatars.githubusercontent.com/u/58092771?v=4"},"body":"Bagas Sanjaya <bagasdotme@gmail.com> writes:\n\n> diff --git a/Documentation/MyFirstContribution.txt b/Documentation/MyFirstContribution.txt\n> index b20bc8e914..5aaf31cb66 100644\n> --- a/Documentation/MyFirstContribution.txt\n> +++ b/Documentation/MyFirstContribution.txt\n> @@ -937,6 +937,23 @@ but want reviewers to look at what they have so far. You can add this flag with\n>  Check and make sure that your patches and cover letter template exist in the\n>  directory you specified - you're nearly ready to send out your review!\n>  \n> +It would help those who review and test your patches to specify on what\n> +commit the patches should be applied to. To do so, use the `--base` option\n> +when running `format-patch`. The option expects hash of the commit the\n> +patchset is based on. Since we base `psuh` on top of `master`, the base\n> +commit hash can be determined by: \n> +\n> +----\n> +$ git show -s --format=\"%H\" master\n> +----\n> +\n> +The output of command above can be passed to `--base` option. Replace `<base>`\n> +with your own hash:\n> +\n> +----\n> +$ git format-patch --cover-letter --base=<base> -o psuh/ master..psuh\n> +----\n> +\n>  [[cover-letter]]\n>  === Preparing Email\n\nThis reads quite awkwardly because a few lines above, we already tell\nthe reader exactly what commands to run:\n\n  Sending emails with Git is a two-part process; before you can prepare the emails\n  themselves, you'll need to prepare the patches. Luckily, this is pretty simple:\n\n  ----\n  $ git format-patch --cover-letter -o psuh/ master..psuh\n  ----\n\nIf we do accept this suggestion (and I am not sure if we should, because\nas Junio said, there are strong conventions for determining the branch\npoint), I think this would be easier to follow if we incorporate it into\nthe existing instructions. Something like..\n\n  Sending emails with Git is a two-part process; before you can prepare the emails\n  themselves, you'll need to prepare the patches. Luckily, this is\n  pretty simple. First, we'll get the hash of the commit the patchset is\n  based on. We call this commit the 'base'.\n\n  ----\n  $ git show -s --format=\"%H\" master\n  ----\n\n  Now, we'll generate the patches, passing the hash of the 'base' to the\n  --base option.\n\n  ----\n  $ git format-patch --cover-letter --base=<base> -o psuh/ master..psuh\n  ----\n\n  [...describe --base=<base> the way we describe the other options].\n"},{"id":"438880","messageId":"xmqqo87q6whk.fsf@gitster.g","threadId":"56719","inReplyTo":"20211015122515.47535-1-bagasdotme@gmail.com","subject":"Re: [PATCH v2] Documentation: specify base point when generating MyFirstContribution patchset","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2021-10-15T17:14:47Z","receivedAt":"2021-10-15T17:14:53Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Bagas Sanjaya <bagasdotme@gmail.com> writes:\n\n> +It would help those who review and test your patches to specify on what\n> +commit the patches should be applied to. To do so, use the `--base` option\n> +when running `format-patch`. The option expects hash of the commit the\n> +patchset is based on. Since we base `psuh` on top of `master`, the base\n> +commit hash can be determined by: \n> +\n> +----\n> +$ git show -s --format=\"%H\" master\n> +----\n\nThat's a littie bit wasteful.\n\nIf we need to teach more stuff (like --format=\"%H\"), one thing that\nmore directly help this exact use case is to teach\n\n    git merge-base master psuh\n\nhere.  But read on.\n\n> +The output of command above can be passed to `--base` option. Replace `<base>`\n> +with your own hash:\n> +\n> +----\n> +$ git format-patch --cover-letter --base=<base> -o psuh/ master..psuh\n> +----\n> +\n\nIf we set up the psuh branch correctly, we can use the `--base=auto`\noption, which would reduce the number of things readers need to\nlearn by one.  Then the whole example in this patch can be reduced\nto (after dropping \"Since we base `psuh` on top of `master`...\" at\nthe end of the previous paragraph):\n\n    patchset is based on.  As we forked `psuh` to build on\n    `origin/master`, we can use the `--base=auto` option when\n    running the `format-patch` command, like so:\n\n    ----\n    $ git format-patch --cover-letter --base=auto -o psuh/ origin/master..psuh\n    ----\n\nThat is one fewer step the user needs to execute.\n\nThis needs one line change in the earlier part of the document (not\ntouched by the patch under discussion here). \n\nIn the [[setup-workspace]] section, we create the psuh by branching\nout of the origin/master (not 'master', so the references to\n`master` in the patch under discussion need to be updated, which I\ndid in the above paragraph already), like so:\n\n    ----\n    $ git checkout -b psuh origin/master\n    ----\n\nAll we need to do is to pass the `-t` option there, i.e.\n\n    ----\n    $ git checkout -t -b psuh origin/master\n    ----\n    \nto make the --base=auto work, I think.\n\nThanks.\n\n\n[Addendum]\n\nAlso, if the tutorial text naturally guides the user to be \"on\" the\n`psuh` branch when the patches are taken from it, we could even\nshorten the command to\n\n    ----\n    $ git format-patch --cover-letter --base=auto -o psuh/ @{u}..\n    ----\n\nThat extra shortening would need a bit more work in the earlier part\nof [[format-patch]] section around the part that says \"Luckily, this\nis pretty simple\".  Basically, we need to invent a plausible story\nfor the user to have done \"git checkout psuh\" earlier, so that it is\nclear to the readers that the `psuh` branch is the current branch.\n\nSo it probably is a good idea to leave it outside the scope of this\ntopic.\n"},{"id":"438920","messageId":"35ccb414-c0fe-ab3a-21aa-ac7b1338df6a@gmail.com","threadId":"56719","inReplyTo":"kl6l4k9i1ame.fsf@chooglen-macbookpro.roam.corp.google.com","subject":"Re: [PATCH v2] Documentation: specify base point when generating MyFirstContribution patchset","fromName":"Bagas Sanjaya","fromEmail":"bagasdotme@gmail.com","sentAt":"2021-10-16T05:16:29Z","receivedAt":"2021-10-16T05:16:40Z","isPatch":true,"sender":{"key":"bagasdotme@gmail.com","avatar":"https://avatars.githubusercontent.com/u/40219486?v=4"},"body":"On 16/10/21 00.06, Glen Choo wrote:\n> This reads quite awkwardly because a few lines above, we already tell\n> the reader exactly what commands to run:\n> \n>    Sending emails with Git is a two-part process; before you can prepare the emails\n>    themselves, you'll need to prepare the patches. Luckily, this is pretty simple:\n> \n>    ----\n>    $ git format-patch --cover-letter -o psuh/ master..psuh\n>    ----\n> \n> If we do accept this suggestion (and I am not sure if we should, because\n> as Junio said, there are strong conventions for determining the branch\n> point), I think this would be easier to follow if we incorporate it into\n> the existing instructions. Something like..\n> \n>    Sending emails with Git is a two-part process; before you can prepare the emails\n>    themselves, you'll need to prepare the patches. Luckily, this is\n>    pretty simple. First, we'll get the hash of the commit the patchset is\n>    based on. We call this commit the 'base'.\n> \n>    ----\n>    $ git show -s --format=\"%H\" master\n>    ----\n> \n>    Now, we'll generate the patches, passing the hash of the 'base' to the\n>    --base option.\n> \n>    ----\n>    $ git format-patch --cover-letter --base=<base> -o psuh/ master..psuh\n>    ----\n> \n>    [...describe --base=<base> the way we describe the other options].\n> \n\nActually it is up to contributors whether they want to include `--base` \nor not.\n\n-- \nAn old man doll... just what I always wanted! - Clara\n"}]}