Proposed: Separate TWiki System Preferences and Site Preferences for ease of upgrade

TWiki has three documented levels of preferences settings:

1. Site-level settings in TWiki.TWikiPreferences
2. Web-level settings in WebPreferences of any web
3. User-level settings in user's home pages, like TWikiGuest

With the current spec, TWiki system settings and site specific settings are both defined in the TWiki.TWikiPreferences. For ease of upgrade it makes sense to separate those two:

1. System-level settings in TWiki.TWikiPreferences
   • All "out of the box" settings of TWiki (some of which are configured by the site owner)
2. Site-specific settings in Main.TWikiPreferences
   • All new settings defined by the site owner

The Main.TWikiPreferences topic is an undocumented feature since TWikiRelease01Feb2003 and can be used for site-specific settings.

On upgrade, an installer can be made smart enough to merge existing TWiki.TWikiPreferences "Set" values into the new TWiki.TWikiPreferences topic. The same can be done for pre-installed Plugin.

The TWiki.TWikiPreferences topic needs to have a note to the site owner to add new site-specific settings only in Main.TWikiPreferences, not in TWiki.TWikiPreferences.

Contributors:
-- MS - 20 Dec 2003
-- PeterThoeny - 22 Dec 2003

Discussions

MS sparked the initial idea in SecureTWikiPreferences

-- PeterThoeny - 22 Dec 2003

A good idea, so long as precedence is clean and simple.

-- JohnTalintyre - 22 Dec 2003

On upgrade, an installer can be made smart enough to merge existing TWiki.TWikiPreferences "Set" values into the new TWiki.TWikiPreferences topic. The same can be done for pre-installed Plugin.

Whilst an installer could do this (and indeed is pretty close to what part of the installer already does) relying on an installer isn't a wise thing - installers can rarely cater for all cases, and any process that an installer does should be able to be dealt with manually. Indeed I've made a number of modifications (which the installer has BTW) which can change preferences, but it prefers to avoid this where possible.

Like others who have said similar things, TWiki.TWikiPreferences should be marked as non-edittable (admin can always override), and point people at Main.TWikiPreferences. Not even an installer should be modifying TWiki.TWikiPreferences.

Whilst a lot can be done in an installer, the cleaner the separation and the less for an installer to do, the better. I've been systematically weeding code out from the installer as I simplify things. (Which is why there's a delay on me re-uploading the TWikiUnixInstaller)

BTW, whilst this helps with separate custom preferences, it doesn't replace the need for that feature - webs need the ability to include preferences from application webs. That technique is an alternate method of performing the same thing that this feature currently gives, but has greater scope.

-- MS - 22 Dec 2003

Just out of curiousity, was this ever formally incorporated into the core? Being as I'm still working on upgrading to Cairo, I think this kind of structural simplification of upgrades would be nice.

-- LynnwoodBrown - 20 Oct 2004

Yes yes yes! I also would prefer to treat the TWiki web just as documentation of the stock system and plugins. By definition, Main has to be touched, so it might as well keep the other customisations. Here comes text factored out from PluginsWebOrTWikiWebForPluginPackages:

---

JonathanCline & MichaelSparks pointed into the right direction: upgrade hell does not stem from having one or two webs. It comes from having documentation & configuration mixed. TWiki, plugins and skins basically contain 3 things:

code

lives in bin, lib

documentation

lives in data/TWiki, data/Main, pub/*

configuration

lives in lib/TWiki.cfg, templates, data/Main, data/TWiki, pub/*

So the most upgrade sensitive stuff is spread all over the place. Obviously, the mission should be to

1. define a common place where to put configs
2. find out how to migrate to that place

Add where: The TWiki web is about 95% documentation. Sounds sensible to get rid of the 5%. slapping in plugin and add-on docs won't hurt, as long as these are read-only.

The Main web as of now is 90% configuration: users & groups, which by definition will be site specific. Why not add the other site configurations as well?
The current semantic of Plugins is just a duplicate of TWiki. Before renaming and reworking it towards Config/Etc whatever, why not stick with Main? If you create complex, permission based form systems, they are intermeshed anyway.

Add how: The current scheme of searching for preferences could be simply extended without breaking the old ways. E.g. finding preferences for a topic in the Foo web:

1. TWiki.TWikiPreferences
2. Foo.WebPreferences
3. Main.SitePreferences
4. Main.WebFooPreferences

Ok, this increases the # of files to open; after a coexistence phase, this can be turned off. But what does this buy us?

1. keep everything in the web which is guaranteed to exist, and which by necessity is site specific
2. override settings like colors, logos etc of the "vendor" web TWiki without touching it
3. override plugin settings without touching the "vendor" defaults in the documentation pages
4. Banners, icons, stylesheets etc could be concentrated in pub/Main/*

Leaves the templates... This is the hardest part. Someone, sometopic, proposed to add sub-directories per skin, so that files could be managed easier with less interference. I don't think, this is the real problem.

The point is, that in the template, looks and features meet! Templates do abstract from feature implemention code, but they cannot possibly help you with new features. And that's what TWiki releases are all about. So similar to patched code, I see no easy way out of patching templates manually. Offloading this task into web topics actually makes your life harder. (Unless you prefer browser's textarea over your local editor.) All this are good points for delivering lots of skins out of the box! And a good point for having the subdirs anyway...

For those, who still can't resist to tweak, but don't habitually cvs their stuff, a simple trick:
Set a global skin preference named custom or yoursite. Then, whenever you touch anything, do not edit foo.tmpl, but create foo.custom.tmpl instead. At upgrade day, diff is your friend.
With a directory skin scheme, this could be similar:

• template/twiki - the original skin
• template/custom - copy of the original or whatever skin you choose
• template/koala ...

---

(Ok, still not 100% on topic, but getting closer :-)

-- PeterKlausner - 21 Oct 2004

I suggest renaming "system-level settings" to "vendor defaults". Similarly, much of what is being called "documentation" is in fact default settings. I agree that these should be installed read-only, and further urge that they be documented as untouchable. Users have a way of editing the wrong file because they don't understand why they have two seemingly-identical config files.

-- KennethPorter - 30 Nov 2004