Re: [PATCH v2] Documentation: specify base point when generating MyFirstContribution patchset

From: Glen Choo <chooglen@google.com>
Date: Oct 15, 2021, 17:06 UTC
Message-ID: <kl6l4k9i1ame.fsf@chooglen-macbookpro.roam.corp.google.com>
In-Reply-To: <20211015122515.47535-1-bagasdotme@gmail.com>

Bagas Sanjaya <bagasdotme@gmail.com> writes:

Show 27 quoted lines

> diff --git a/Documentation/MyFirstContribution.txt b/Documentation/MyFirstContribution.txt
> index b20bc8e914..5aaf31cb66 100644
> --- a/Documentation/MyFirstContribution.txt
> +++ b/Documentation/MyFirstContribution.txt
> @@ -937,6 +937,23 @@ but want reviewers to look at what they have so far. You can add this flag with
>  Check and make sure that your patches and cover letter template exist in the
>  directory you specified - you're nearly ready to send out your review!
>  
> +It would help those who review and test your patches to specify on what
> +commit the patches should be applied to. To do so, use the `--base` option
> +when running `format-patch`. The option expects hash of the commit the
> +patchset is based on. Since we base `psuh` on top of `master`, the base
> +commit hash can be determined by: 
> +
> +----
> +$ git show -s --format="%H" master
> +----
> +
> +The output of command above can be passed to `--base` option. Replace `<base>`
> +with your own hash:
> +
> +----
> +$ git format-patch --cover-letter --base=<base> -o psuh/ master..psuh
> +----
> +
>  [[cover-letter]]
>  === Preparing Email

This reads quite awkwardly because a few lines above, we already tell the reader exactly what commands to run:

  Sending emails with Git is a two-part process; before you can prepare the emails
  themselves, you'll need to prepare the patches. Luckily, this is pretty simple:

  ----
  $ git format-patch --cover-letter -o psuh/ master..psuh
  ----

If we do accept this suggestion (and I am not sure if we should, because as Junio said, there are strong conventions for determining the branch point), I think this would be easier to follow if we incorporate it into the existing instructions. Something like..

  Sending emails with Git is a two-part process; before you can prepare the emails
  themselves, you'll need to prepare the patches. Luckily, this is
  pretty simple. First, we'll get the hash of the commit the patchset is
  based on. We call this commit the 'base'.

  ----
  $ git show -s --format="%H" master
  ----

  Now, we'll generate the patches, passing the hash of the 'base' to the
  --base option.

  ----
  $ git format-patch --cover-letter --base=<base> -o psuh/ master..psuh
  ----

  [...describe --base=<base> the way we describe the other options].