Re: [PATCH 1/3] docs: correct receive.advertisePushOptions default

From: Jonathan Nieder <jrnieder@gmail.com>
Date: May 5, 2017, 23:58 UTC
Message-ID: <20170505235857.GJ28740@aiede.svl.corp.google.com>
In-Reply-To: <28c40105e53a4d4d828092bc1697fff8992419d6.1494027001.git.jonathantanmy@google.com>

Jonathan Tan wrote:

Show 29 quoted lines

> In commit c714e45 ("receive-pack: implement advertising and receiving
> push options", 2016-07-14), receive-pack was taught to (among other
> things) advertise that it understood push options, depending on
> configuration. It was documented that it advertised such ability by
> default; however, it actually does not. (In that commit, notice that
> advertise_push_options defaults to 0, unlike advertise_atomic_push which
> defaults to 1.)
>
> Update the documentation to state that it does not advertise the ability
> by default.
>
> Signed-off-by: Jonathan Tan <jonathantanmy@google.com>
> ---
>  Documentation/config.txt | 5 ++---
>  1 file changed, 2 insertions(+), 3 deletions(-)
> 
> diff --git a/Documentation/config.txt b/Documentation/config.txt
> index 475e874d5..f49a2f3cb 100644
> --- a/Documentation/config.txt
> +++ b/Documentation/config.txt
> @@ -2620,9 +2620,8 @@ receive.advertiseAtomic::
>  	capability, set this variable to false.
>  
>  receive.advertisePushOptions::
> -	By default, git-receive-pack will advertise the push options
> -	capability to its clients. If you don't want to advertise this
> -	capability, set this variable to false.
> +	When set to true, git-receive-pack will advertise the push options
> +	capability to its clients.

Good catch.

Reviewed-by: Jonathan Nieder <jrnieder@gmail.com>

Possible improvements:

- Should this also say "The default is false"?

- git-receive-pack(1) doesn't say anything about push options, so
  without more context it's hard for a new git admin taking over
  from someone who had set this up to understand what's going on.
  Should this have a pointer to the pre-receive + post-receive
  sections of githooks(5)?

- Speaking of which, should git-receive-pack(1) say something
  about push options (for example to also have a pointer to
  githooks(5))?

- git-push(1) has the same problem: when describing the -o option, it
  doesn't give a pointer to where to find more detail (though it's a
  little more helpful then this one since it includes the word "hook").

Thanks, Jonathan