Re: [PATCH] MyFirstContribution: teach to use "format-patch --base=auto"

Bagas Sanjaya <bagasdotme@gmail.com> writes:

Hmph, the log message changes, relative to what is queued, look like so:

    Let's encourage first-time contributors to tell us what commit they
    based their work[-on-] with the format-patch invocation. As the example
    already forks from origin/master and branch.autosetupmerge by
    default records the upstream when the psuh branch was created, we
    can use --base=auto for this.  Also, mention {+to the readers+} that
    the range of commits can simply be given with `@{u}` if they are on the
    `psuh` branch already.

    As we are getting one more option on the command line, and spending
    one paragraph each to explain them, let's reformat that part of the
    description as a bulletted list.

Contributors will tell us what commit they based their work on, and removal of "on" does not look like fixing grammar to me (it looks more like breaking). Adding "to the readers" is not _wrong_ per-se, but given that everything you write in the documentation is telling to the readers and to nobody else, it does not seem to add anything. It is something different from "fix grammar".

In short, I do not think anything needs to be changed in the proposed log message in the version that has been queued.

Everything after "The `auto` value will..." is new and is a welcome addition, as I agree that giving a brief explanation of the option is a good idea. Thanks for highlighting the careless addition I made in the original version.

But use of verb "track" in the format-patch documentation that was copied to this patch should be fixed first. format-patch does not change any history and it does not track anything. Perhaps "track" -> "compute", e.g.

    The `auto` value will cause `format-patch` to compute the base
    commit automatically, which is the merge base of tip commit of the
    remote-tracking branch and the specified revision range.

And the matching correction to the existing documentation should look like the attached patch.

Thanks.

----- >8 --------- >8 --------- >8 --------- >8 --------- >8 ----
Subject: [PATCH] format-patch (doc): clarify --base=auto

What --base=auto tells format-patch is to compute the base commit itself, using the tracking information. It does not make anything track anything.

Tighten the phrasing so that it won't be copied and pasted to other places.

Signed-off-by: Junio C Hamano <gitster@pobox.com>
---
 Documentation/git-format-patch.txt | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)