Changes have been made in Git for this ticket:

There are several places where backends can be defined (Bug #9745).

  1 files changed, 6 insertions(+), 6 deletions(-)
http://git.horde.org/horde-git/-/commit/83480db086095963a62cfb8b473843aa5571fefc

You have different options that look good to me, and I don't feel in 
position to compare. Whatever you decide to do, make sure that the 
description of the $conf[server][server_list] option points to it. It 
currently reads: "Should we display a list of servers (defined in 
config/backends.php)...": this was the text that actually misled Joe 
Average into editing that file.

I think you are both exaggerating, but I agree that we can improve 
both, teaching the new way of configuration, and to help admins to not 
shoot themselves into their feet.

How about picking up one of Michael's earlier ideas:
- Move the default configurations to config/default/, so that they are 
not immediately visible when looking into config/, and are not in the 
place where admins coming from H3 expect them.
- Create *.local.php.dist example files that can be copied to 
*.local.php and contain working, useful examples for configuration 
customizations, similar to hooks.php.dist
- If we move the defaults to default/ we could probably even drop the 
".local" and use the old file names again.

But we are *not* going back to having the admins update their 
configuration files (beside conf.php or course) after each update.

Being the Joe Average sysadmin whose dumbness and haste you're trying 
to address, I still believe that having backends.php. renamed to 
backends.php.dist is a viable solution.

I understand that in this way it would not work "out of the box" with 
imap server on localhost, but:

  - I have no installation with imap server on localhost (this 
probably means I'm not really Joe Average)

  - [Doesn't work -> do something -> works] is an annoying fact of 
life Joe average can understand and is somewhat used to. In this 
specific case, having to tell the mailserver location to a webmail 
system can be seen as unavoidable.

  - [Works -> months pass -> upgrade -> doesn't work/lose config] is 
much more annoying and fosters the "Don't upgrade" school of thought, 
with obvious security implications.

My derailing in the last scenario was of course a mistake, but I think 
my mistake was not uncommon.

Still think this change is a terrible idea.  Didn't dwell on the 
subject on dev@ 
(http://lists.horde.org/archives/dev/Week-of-Mon-20110214/025823.html) 
since it seemed I was outnumbered, but the concerns I raised (or were 
thinking about) are starting to show themselves so I will at least 
mention a few more here.

First, this is a *huge*, not readily apparent, change from H3.  I've 
been getting hammered lately for making changes that change the status 
quo from H3 because this is what users/admins are "used to".  Don't 
see how this is any different.

Adding a disclaimer to the config files is not going to change much.   
Especially since I agree with Chuck - the location of the disclaimer 
now pretty much means that nobody is going to see it, especially if 
they are used to dealing with H3 configs.  But even if you move it 
closer to the actual PHP code, people are still going to ignore.   
After all, if it was me, I'm going to open up the config file, search 
for a string, and start editing anyway.

Second, I can only imagine the e-mail support in the future on the 
mailing list.  Right now (H3), an email in a support thread might say:

Edit horde/config/registry.php and add a 'status' entry to the ingo 
block.  The valid list of status options can be found at the top of 
the file.

In the future, this is what it will entail:

Open horde/config/registry.php and determine the full PHP array 
variable string (in this case $this->applications['ingo']['status']).   
Also, make sure you check the top of that file for the various status 
entries and remember this value.  Then open 
horde/config/registry.php.local.  If this file doesn't exist, you will 
need to create this file.  Make sure this file is readable by the user 
the PHP process is running as.  Then make sure 
horde/config/registry.php.local begins with this exact string: "<?php 
".  Now you can paste the PHP variable string into this file, along 
with the value that you should have determined when looking at the 
original configuration file.  You will probably want to comment this 
entry also since, in isolation, you will likely forget the context of 
this change in the future.

No... I saw that, but it doesn't really stand out from the rest of the 
comments, and I think it should be both right above and right below 
the PHP section of the file.

Like this one?

https://github.com/horde/horde/blob/master/imp/config/backends.php#L6

I think we probably can/should make the "put edits in a local file" 
disclaimer bigger (and right above and below the code parts of the 
file).

There is no backends.php.dist. Read docs/UPGRADING.

When upgrading with pear upgrade -c horde, imp/config/backends.php is 
overwritten. I believe that this file, which holds essential IMP 
configuration informations, should not be overwritten. 
backends.php.dist should be upgraded instead.