Re: [PATCH 2/2] doc: documentation update for the branch track changes

[Junio C Hamano <gitster@pobox.com>]

Jay Soffian <jaysoffian@gmail.com> writes:

> Documents the branch.autosetupmerge=always setting and usage of --track
> when branching from a local branch.
>
> Signed-off-by: Jay Soffian <jaysoffian@gmail.com>
> ---
> I was trying to change too much at once. This is the bare minimum to
> document the functionality changes.

This is very much appreciated.  Bite-sized changes make
reviewing much more pleasant.

> diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt
> index 7e8874a..c5426a5 100644
> --- a/Documentation/git-branch.txt
> +++ b/Documentation/git-branch.txt
> @@ -105,20 +104,19 @@ OPTIONS
>  	Display the full sha1s in output listing rather than abbreviating them.
>  
>  --track::
> -	Set up configuration so that git-pull will automatically
> -	retrieve data from the remote branch.  Use this if you always
> -	pull from the same remote branch into the new branch, or if you
> -	don't want to use "git pull <repository> <refspec>" explicitly.
> -	This behavior is the default.  Set the
> -	branch.autosetupmerge configuration variable to false if you
> -	want git-checkout and git-branch to always behave as if
> -	'--no-track' were given.
> +	When creating a new branch, set up configuration so that git-pull
> +	will automatically retrieve data from the start point, which must be
> +	a branch. Use this if you always pull from the same upstream branch
> +	into the new branch, or if you don't want to use "git pull
> +	<repository> <refspec>" explicitly. ...

Micronit; I think this ", or" should be ", and".

> diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt
> index b4cfa04..7c7cfb1 100644
> --- a/Documentation/git-checkout.txt
> +++ b/Documentation/git-checkout.txt
> @@ -48,21 +48,19 @@ OPTIONS
>  	may restrict the characters allowed in a branch name.
>  
>  --track::
> ...
>  --no-track::
> ...

Micronit; we would want to create track-options.txt and then
include::track-options.txt[] from here and in git-branch.txt
(that can be done later).

Otherwise, the patch looks fine, and I'll queue this as-is,
together with your [1/2] (with the "oops, commit message is
stale" amended in).  We can incrementally improve on these
in-tree from here on.

I am very tempted to squish the "s/,or /, and/" change in while
applying [2/2], though.

By the way, please do not get discouraged to send-in the doc
clean-ups.  I "gave up (for now)" last night because it was
getting late, I had other patches to review and accept/respond,
and I felt I did not have time to comment on a patch that mixes
clean-ups and feature enhancements at that point.

It is a good idea to organize a series so that clean-ups to
existing stuff that you are going to touch come first, and then
your own enhancements come on top, for a few reasons:

 (1) It is good for reviewers, because each can be looked at
     individually.

     * A clean-up is not supposed to change the behaviour and/or
       semantics unless it is a bugfix.  An error in rewriting
       becomes easier to spot if it is done standalone.
       Otherwise the reviewers need to wonder "why is it this
       way now?  Is it a thinko, or is it because it interacts
       with the new feature?"

     * An enhancement on top of the cleaned-up base will be
       smaller and easier to understand what gets changed.

 (2) It is good for the maintainer, for the same reason as
     above, and in addition, even when the list does not yet
     agree with the proposed enhancements, the clean-ups to
     allow any other future work (not limited to the
     contributor's) may be received favorably already.  The
     clean-up can be applied early while potentially
     controversial enhancements are still being discussed and
     polished.  This reduces the total amount of changes in
     flight --- smaller number of things to keep track of.
     
 (3) It is good for contributors, because the new work (which is
     what the contributors are more interested in) can be done
     on solidified base, and the patch that may need to go
     through multiple rounds of polishing would become smaller,
     if clean-ups are accepted independently in earlier rounds.

The same principle applies to both code and documentation.