create new tag
, view all tags

TWiki Upgrade Strategy

We need to make it easier to upgrade a running TWiki.

We need to have a roadmap to solve the whole problem.

That's the aim of this topic....

Existing relevant discussions

Please add what you know!

Topic What it covers
TWikiBetaReleaseDiscussions Mostly me arguing that we need to do this smile -- MG
TWikiUpgradeGuide This contains the instructions a user currently has to work from if they want to upgrade. It is about upgrading to 1 Feb 03 from something older!
CairoReleaseUpgradeGuide This appears to be the "official" place where notes about "how to upgrade to Cairo" are intended to be written, with the goal of assimilating them into the next "UpgradeGuide". There are a few notes there that need to be (and are yet to be) assimilated here.
EasierUpgrades * Discussion * Option: Provide tools/makefile to assist * Issue: Dealing with Patched Servers * Issue: Local customisations (code & settings) versus defaults (code & settings) o TWikiTopicUpgradeScript
TWikiTopicUpgradeScript This is a script that uses the RCS logs to solve the problem of "what if new topic files coming with the upgrade replace changes made locally to the existing versions of those topics?". It relies on the upgrader installing the RCS logs made during the development of the upgrade. Controversial.
RenameMainWebToHome This is about changes that will make it easier to understand TWiki, but it also is in the direction of putting the 'user' stuff somewhere cleaner, so it is relevant.
EZUsabilityUpgradePlan Red herring thrown up by a search: this is a plan for upgrading all TWiki docs, nothing to do with the issue of upgrading existing TWikis
RequestReviewTWikiUpgradeGuide Red herring thrown up by a search: this is a request to review 28 Feb 03 release upgrade guide.

Big Picture Questions

What are the fundamental problems for a TWiki upgrade?

  • Re-linking back in new local webs

  • Changes made locally to topics that will be upgraded: distinguishing between local changes that need to be merged and those that are obsolete... then doing the merge/discard.

  • Settings/options

  • Directory structure (for TWikis on hosted sites)

What tool/mechanism should be provided as "the upgrade tool"?

  • Web-based tool?

  • Makefile?

  • Perl

PT argues (below) for a perl script to handle install, because (for a start) perl is guaranteed to be present.

What TWiki architectural things need to be changed in the interests of "Clean Upgrade"?

These are the things that cause backward compatibility headaches. They will be dealt with according to this policy (currently being discussed below):

"The Roadmap for implementation of a decent upgrade strategy will include a single well-thought out place where backward compatibility with nuisance features will be broken.  Users will be transitioned across this break with helpful once-off tools."

  • Where configurations are stored?

  • ???

The Roadmap

Well, we don't have a roadmap to upgradability nirvana yet... so here's a plan to get a roadmap:

  1. Figure out what bits & pieces are out there already
  2. Collate the answers to the serious questions above
  3. Figure out a seqence of improvements!

And here is what it looks like at first pass:

1) What's out there:

  • Sven's topic upgrade script

that's all.

Well not quite - there's also the TWikiUnixInstaller, but so far I haven't seen how to get mileage out of that.

2) Answers to hard questions:

  • Relinking back in old webs: does getting topics right fix this? Yes I think it does: there's hardly anything to do!

  • Topic changes: Sven's script handles these by RCS diff. Might not be a complete solution, but certainly a good start

  • Settings/Options: So far setlib.cfg and TWiki.cfg are the non-topic based options I've found to worry about. Any changes that a new release makes to these need to be manually considered by upgrading admins. Thus a script to present these differences seems like the way to go.

  • Directory structure - still investigating (problem is that in a hosted environment, bin (for example) may not be able to be under the same tree as lib (as an example).


Upgradability of TWiki clearly requires significant restructuring of "how things are done".

(Colas notes some additional things below)

It's been clear for some time that this kind of change would not make it to Cairo.

I have implemented a short-term "at least it is some help, better than none" solution based on "help the user upgrade with things the way that they are".

You can find it at UpgradeTWiki.

Meanwhile, any and all discussion of "how things should be changed for the future" is what we need!


I'd like this page to contain information about the TWikiUpgradeStrategy: options and requirements.

Meta-information ... discussion about those options and requirements... are extremely welcome and sought after... here: TWikiUpgradeStrategyDiscussion.

-- MartinGregory - 21 Jun 2004

I've just released a TWikiReleaseTrackerPlugin - its purpose is to tell you how different your install is from any given release. Works fine on Cairo, but am having some trouble on my Athens and Beijing installs: I've run out of time for now (on holiday for 10 days) but it is in a stage suitable for more widespread testing.

You can try it out on my Cairo install, but I would appreciate if you'd then try installing it for yourself. (It should be very useful to anyone with a new Cairo install). I'll be around occasionally to check the TWikiReleaseTrackerPluginDev topic, my email and this topic, but am unlikely to be reading anything else until my return. I might get on TWikiIRC, especially if anyone asks me to.

-- MartinCleaver - 04 Aug 2004

I think we should just make sure that no distributed files are ever edited locally, plain and simple.

  • TWiki.cfg should not be distributed. Its contents (default values) should be moved into the code. users would just create a TWiki.cfg from scratch with only values differing from default listed.
  • WebPreferences topics should not be distributed either. TWiki defaults should be in the code, users being free to create WebPreferences topics. The verbose explanations should go into a single documentation topic in the TWiki web, not being duplicated in topics. Even the WebNotify topics should be emptied, leaving only a pointer to (centralized in TWiki) explanations.
Then a perl script could be made to optionally detect things to change after upgrade (if WebPreferences syntax changes, for instance). Doing otherwise is just doomed.

PS: a nice functionality could be in topics a * Set EDITHELP = topic that will pop up a help window with the contents of the specified topic, avoiding to pre-fill topic with what is basically help text that shouldn't be there

-- ColasNahaboo - 05 Aug 2004

Edit | Attach | Watch | Print version | History: r39 < r38 < r37 < r36 < r35 | Backlinks | Raw View | Raw edit | More topic actions
Topic revision: r39 - 2005-06-24 - WillNorris
  • Learn about TWiki  
  • Download TWiki
This site is powered by the TWiki collaboration platform Powered by Perl Hosted by OICcam.com Ideas, requests, problems regarding TWiki? Send feedback. Ask community in the support forum.
Copyright © 1999-2018 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.