Re: [PATCH] gitweb/INSTALL: Simplify description of GITWEB_CONFIG_SYSTEM

Drew Northup [off-list ref] writes:

quoted

+  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.

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.

In order to just pick and use the more appropriate one (or a useful
combination of the two), a clean description of what each of them do
without historical cruft is more readable and useful, isn't it?  I
would expect that most of them who are newly configuring a system
would pick COMMON one and override per instance as needed, without
touching the SYSTEM one (fallback default) after reading the above,
and that is what we want to happen.

Do you think sysadmins need a history lesson to understand why there
are two different possibilities?

For example, bash reads some but not all possible configuration
files. I would expect .bashrc to be read even for login shells after
reading .bash_login; alas, that is not what happens.  The manual
does not apologize that the authors now know better and understand
that it is a stupid behaviour.  The order the rc files are read is
just described matter-of-factly, and it gives sufficient information
without unnecessary backstory.

I think the new text conveys the necessary information to the
intended audience with more clarity without the history lesson or
the record of your past frustration. Am I mistaken?

Junio C Hamano wrote:

In order to just pick and use the more appropriate one (or a useful
combination of the two), a clean description of what each of them do
without historical cruft is more readable and useful, isn't it?  I
would expect that most of them who are newly configuring a system
would pick COMMON one and override per instance as needed, without
touching the SYSTEM one (fallback default) after reading the above,
and that is what we want to happen.

Do you think sysadmins need a history lesson to understand why there
are two different possibilities?

[...]

I think the new text conveys the necessary information to the
intended audience with more clarity without the history lesson or
the record of your past frustration. Am I mistaken?

Note also that this is about *gitweb/INSTALL*, which is meant to be
*short* and succint description on how to install gitweb, and not
about the reference documentation: gitweb(1) or gitweb.conf(5).

Description of historical behavior (and backward compatibility)
has place (if any) in manpages, not gitweb/INSTALL.
-- 
Jakub Narębski

On Tue, Apr 16, 2013 at 3:11 AM, Jakub Narębski [off-list ref] wrote:

Junio C Hamano wrote:

quoted

In order to just pick and use the more appropriate one (or a useful
combination of the two), a clean description of what each of them do
without historical cruft is more readable and useful, isn't it?  I
would expect that most of them who are newly configuring a system
would pick COMMON one and override per instance as needed, without
touching the SYSTEM one (fallback default) after reading the above,
and that is what we want to happen.

Do you think sysadmins need a history lesson to understand why there
are two different possibilities?

[...]

quoted

I think the new text conveys the necessary information to the
intended audience with more clarity without the history lesson or
the record of your past frustration. Am I mistaken?

Note also that this is about *gitweb/INSTALL*, which is meant to be
*short* and succint description on how to install gitweb, and not
about the reference documentation: gitweb(1) or gitweb.conf(5).

Description of historical behavior (and backward compatibility)
has place (if any) in manpages, not gitweb/INSTALL.
--
Jakub Narębski

Let us then agree that it should be mentioned somewhere in
gitweb.conf.txt then (as it currently is not).

--
-Drew Northup
--------------------------------------------------------------
"As opposed to vegetable or mineral error?"
-John Pescatore, SANS NewsBites Vol. 12 Num. 59

On Tue, Apr 16, 2013 at 12:36 AM, Junio C Hamano [off-list ref] wrote:

Drew Northup [off-list ref] writes:

quoted

quoted

+  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.

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.

In order to just pick and use the more appropriate one (or a useful
combination of the two), a clean description of what each of them do
without historical cruft is more readable and useful, isn't it?

I am not demanding the retention of cruft, and the rewording is
definitely more pleasant to read.

 I
would expect that most of them who are newly configuring a system
would pick COMMON one and override per instance as needed, without
touching the SYSTEM one (fallback default) after reading the above,
and that is what we want to happen.

Do you think sysadmins need a history lesson to understand why there
are two different possibilities?

We don't need a full history lesson. What we do need to know is that
"Hey, they don't do that the way everybody else does because it would
break things." That's enough to get the point across, and as Jakub
noted gitweb.conf.txt is the correct place for it.

For example, bash reads some but not all possible configuration
files. I would expect .bashrc to be read even for login shells after
reading .bash_login; alas, that is not what happens.  The manual
does not apologize that the authors now know better and understand
that it is a stupid behaviour.  The order the rc files are read is
just described matter-of-factly, and it gives sufficient information
without unnecessary backstory.

I think the new text conveys the necessary information to the
intended audience with more clarity without the history lesson or
the record of your past frustration. Am I mistaken?

The back-story isn't needed; the "Hey this is different" part is. I
think Jakub's suggestion of covering that (succinctly) in
gitweb.conf.txt is the correct solution.

--
-Drew Northup
--------------------------------------------------------------
"As opposed to vegetable or mineral error?"
-John Pescatore, SANS NewsBites Vol. 12 Num. 59

Signed-off-by: Jakub Narebski <redacted>
---
This can be either squashed with previous patch to gitweb/INSTALL,
kept as separate patch or discarded.

Drew: gitweb(1) or gitweb.conf(5) solution is more involved, so
perhaps something like that?

 gitweb/INSTALL |    3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/gitweb/INSTALL b/gitweb/INSTALL
index 7ad1050..386e62f 100644
--- a/gitweb/INSTALL
+++ b/gitweb/INSTALL

@@ -243,7 +243,6 @@ 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 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

@@ -252,6 +251,8 @@ for gitweb (in gitweb/README), and gitweb.conf(5) manpage.
   system-wide configuration file override those from common system-wide
   configuration file.
 
+  (Idiosyncratic GITWEB_CONFIG_SYSTEM is present for backward compatibility.)
+
 - The gitweb config file is a fragment of perl code. You can set variables
   using "our $variable = value"; text from "#" character until the end
   of a line is ignored. See perlsyn(1) for details.

-- 
1.7.10.4

On Tue, Apr 16, 2013 at 8:26 AM, Jakub Narębski [off-list ref] wrote:

Drew: gitweb(1) or gitweb.conf(5) solution is more involved, so
perhaps something like that?

That or: (or both I suppose....hopefully not too mangled by Google's
mail gadget)

-- >8 --
Subject: [PATCH] Documentation/gitweb.conf.txt: Move note about config
order precedence

To go along with Jakub Narebski's cleanup of gitweb/INSTALL; making
it clear that gitweb's config files work differently than a lot of
other system-wide software. This is unobtrusive yet to the point.
---
 Documentation/gitweb.conf.txt | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/Documentation/gitweb.conf.txt b/Documentation/gitweb.conf.txt
index eb63631..05c81e7 100644
--- a/Documentation/gitweb.conf.txt
+++ b/Documentation/gitweb.conf.txt

@@ -55,7 +55,8 @@ following order:
    then fallback system-wide configuration file (defaults to

'/etc/gitweb.conf').

 Values obtained in later configuration files override values obtained earlier
-in the above sequence.
+in the above sequence. This is different from many system-wide software
+installations and will stay this way for historical reasons.

 Locations of the common system-wide configuration file, the fallback
 system-wide configuration file and the per-instance configuration file
--
1.8.0


--
-Drew Northup
--------------------------------------------------------------
"As opposed to vegetable or mineral error?"
-John Pescatore, SANS NewsBites Vol. 12 Num. 59

Forgot the S-O-B...

On Tue, Apr 16, 2013 at 8:47 AM, Drew Northup [off-list ref] wrote:

On Tue, Apr 16, 2013 at 8:26 AM, Jakub Narębski [off-list ref] wrote:

quoted

Drew: gitweb(1) or gitweb.conf(5) solution is more involved, so
perhaps something like that?

That or: (or both I suppose....hopefully not too mangled by Google's
mail gadget)

Subject: [PATCH] [PATCH] Documentation/gitweb.conf.txt: Move note
about config order precedence

To go along with Jakub Narebski's cleanup of gitweb/INSTALL; making
it clear that gitweb's config files work differently than a lot of
other system-wide software. This is unobtrusive yet to the point.

Signed-off-by: Drew Northup <redacted>
---
 Documentation/gitweb.conf.txt | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/Documentation/gitweb.conf.txt b/Documentation/gitweb.conf.txt
index eb63631..05c81e7 100644
--- a/Documentation/gitweb.conf.txt
+++ b/Documentation/gitweb.conf.txt

@@ -55,7 +55,8 @@ following order:
    then fallback system-wide configuration file (defaults to

'/etc/gitweb.conf').

 Values obtained in later configuration files override values obtained earlier
-in the above sequence.
+in the above sequence. This is different from many system-wide software
+installations and will stay this way for historical reasons.

 Locations of the common system-wide configuration file, the fallback
 system-wide configuration file and the per-instance configuration file
--
1.8.0

--
-Drew Northup
--------------------------------------------------------------
"As opposed to vegetable or mineral error?"
-John Pescatore, SANS NewsBites Vol. 12 Num. 59

Drew Northup wrote:

                            This is unobtrusive yet to the point.

I agree with the spirit.

[...]

That makes it sound like the "per instance overrides common overrides
built-in" cascading is what is unusual and what we need to apologize
for.

How about something like the following?  (It uses a BUGS section to
make the warning easy to notice for people tracking down confusing
behavior by searching for "gitweb.conf".)

diff --git i/Documentation/gitweb.conf.txt w/Documentation/gitweb.conf.txt
index eb63631..ea0526e 100644
--- i/Documentation/gitweb.conf.txt
+++ w/Documentation/gitweb.conf.txt

@@ -857,6 +857,13 @@ adding the following lines to your gitweb configuration file:
 	$known_snapshot_formats{'zip'}{'disabled'} = 1;
 	$known_snapshot_formats{'tgz'}{'compressor'} = ['gzip','-6'];
 
+BUGS
+----
+Debugging would be easier if the fallback configuration file
+(`/etc/gitweb.conf`) and environment variable to override its location
+('GITWEB_CONFIG_SYSTEM') had names reflecting their "fallback" role.
+The current names are kept to avoid breaking working setups.
+
 ENVIRONMENT
 -----------
 The location of per-instance and system-wide configuration files can be

On Tue, Apr 16, 2013 at 6:26 PM, Jonathan Nieder [off-list ref] wrote:

Drew Northup wrote:

quoted

                            This is unobtrusive yet to the point.

I agree with the spirit.

[...]

quoted

--- a/Documentation/gitweb.conf.txt
+++ b/Documentation/gitweb.conf.txt

@@ -55,7 +55,8 @@ following order:
    then fallback system-wide configuration file (defaults to

'/etc/gitweb.conf').

 Values obtained in later configuration files override values obtained earlier
-in the above sequence.
+in the above sequence. This is different from many system-wide software
+installations and will stay this way for historical reasons.

That makes it sound like the "per instance overrides common overrides
built-in" cascading is what is unusual and what we need to apologize
for.

I don't think were apologizing for anything. It is helpful to say "we
do some things differently here and don't plan on changing for a very
important reason.

I don't disagree with this, as some would consider the naming to be a
bug, but after having been given a good schooling on the git list a
while back as to why it is the way it is I'm hesitant to label "has
history" as a bug.

--
-Drew Northup
--------------------------------------------------------------
"As opposed to vegetable or mineral error?"
-John Pescatore, SANS NewsBites Vol. 12 Num. 59