On Fri, Apr 12, 2013 at 6:20 PM, Jakub Narębski <jna...@gmail.com> wrote:

> -- >8 --
> Subject: [PATCH] gitweb/INSTALL: Simplify description of GITWEB_CONFIG_SYSTEM
> The flow of the text describing GITWEB_CONFIG_SYSTEM and
> GITWEB_CONFIG_COMMON in gitweb/INSTALL is awkward.  "This is
> bad. Oh the other hand, better is broken. Therefore ..." forces
> readers to make multiple guesses while reading: "ok, bad, so you plan
> to change it and warn us about upcoming change?  oh, not that,
> changing it is bad, so we have to live with it?  oh, not that, there
> is another one that is common and that is what we can use".
> Better rewrite said paragraph to avoid such a mental roller-coaster in
> the first place.
> Signed-off-by: Junio Hamano <gits...@pobox.com>
> Signed-off-by: Jakub Narebski <jna...@gmail.com>
> ---
>  gitweb/INSTALL |   14 ++++++--------
>  1 file changed, 6 insertions(+), 8 deletions(-)
> diff --git a/gitweb/INSTALL b/gitweb/INSTALL
> index 6d45406..7ad1050 100644
> --- a/gitweb/INSTALL
> +++ b/gitweb/INSTALL
> @@ -243,14 +243,12 @@ for gitweb (in gitweb/README), and gitweb.conf(5) 
> manpage.
>    GITWEB_CONFIG_SYSTEM build configuration variable, and override it
>    through the GITWEB_CONFIG_SYSTEM environment variable.
> -  Note that if per-instance configuration file exists, then system-wide
> -  configuration is _not used at all_.  This is quite untypical and suprising
> -  behavior.  On the other hand changing current behavior would break 
> backwards
> -  compatibility and can lead to unexpected changes in gitweb behavior.
> -  Therefore gitweb also looks for common system-wide configuration file,
> -  normally /etc/gitweb-common.conf (set during build time using build time
> -  configuration variable GITWEB_CONFIG_COMMON, set it at runtime using
> -  environment variable with the same name).  Settings from per-instance or
> +
> +  Note that the GITWEB_CONFIG_SYSTEM system-wide configuration file is
> +  only used for instances that lack per-instance configuration file.
> +  You can use GITWEB_CONFIG_COMMON common system-wide configuration
> +  file (normally /etc/gitweb-common.conf) to keep common default
> +  settings that apply to all instances.  Settings from per-instance or
>    system-wide configuration file override those from common system-wide
>    configuration file.

The point of wording it such that it was explicitly noted that the
supposed "system-wide" settings were really just "system-wide
defaults" (which would be ignored wholesale if any one setting was
overridden locally) was due to the fact that most of the time server
administrators don't deal with software that idiosyncratic. Prior to
the addition of GITWEB_CONFIG_COMMON there was no method for setting
up a sane default template that wouldn't be discarded wholesale upon
any one configuration parameter being overridden.

That's the point of explaining SPECIFICALLY why the then current
behavior wasn't being replaced, and this other mechanism (which would
otherwise have no obvious reason for existing) was being introduced.
So, unfortunately,  if we remove the "mental roller coaster" part of
the explanation entirely we can expect to end up in exactly the
situation that I complained about to begin with. (Or we could just do
this the way everybody else does, with partial overrides being the
common case, starting at 2.x and no longer have the mental roller
coaster problem at all.)

As I'm the one that complained loudly enough to get this change to be
made in the first place I'd appreciate being kept in the loop in this

-Drew Northup
"As opposed to vegetable or mineral error?"
-John Pescatore, SANS NewsBites Vol. 12 Num. 59
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Reply via email to