Re: Announcing 3 git docs: Best Practices, fixing mistakes, post-production editing

From: Junio C Hamano <gitster@pobox.com>
Date: Mar 4, 2012, 23:26 UTC
Message-ID: <7vhay46j7v.fsf@alter.siamese.dyndns.org>
In-Reply-To: <201203041920.q24JKk3h024813@no.baka.org>

Seth Robertson <in-gitvger@baka.org> writes:

Show 15 quoted lines

> In message <7v399uxxkq.fsf@alter.siamese.dyndns.org>, Junio C Hamano writes:
>     Just a few I noticed that are dubious to be in a document that is meant to
>     describe "best practices".
> ...
>     "Don't panic"
>     -------------
>
>     * As we never "auto-stash", anything that is on stash is by definition
>       what the user deliberately placed, just like a commit on a branch that
>       the user may have forgotten.  So it is strange to count it as one of the
>       three places that "lost" commit may be hiding.  If you make it four and
>       add "a branch you might have forgotten" to the mix, it would make a bit
>       more sense, though.
>
> I do.

You don't. You say "There are THREE places where "last" changes can be hiding" and list these three things, not four.

Show 12 quoted lines

>     "Do keep up to date"
>     --------------------
>
>     * You explained in "Do choose a workflow" section that different workflows
>       suite different projects.  ... it
>       would be more useful to say in what workflow and the workflow elements
>       such as "pull --rebase" you advocate in this section are suited (you do
>       not have to say in what other workflow they are inappropriate).
>
> In the pull --rebase section, I spend one short paragraph talking
> about why I think it is a good idea and four providing arguments
> against it.  In my opinion,...

I do not know if you have updated the version seen on the web since the review comments, but I was merely suggesting that "what I recommend here may not be desirable for some workflows" without spelling out what these workflows are would be less helpful to readers than being more explicit, i.e. "these suggestions are good for this and that workflows".

This section by nature of what is discussed is bound to be incomplete and will not be "universal truth" as there does no "universal truth" exist. Letting the users know that for what kind of workflows these are good suggestions upfront will help them to decide if the recommendations are applicalble to them.