Foswiki - when Community matters (riff inspired by AntonioRaffaeleCosta)

Plan for re-branding the code and documentation

Heavily refactored the thread-mode and fractured topic that was here previously. Look at rev 33 to recover content if you think something critical was missed.

The problem

1. We cannot use the TWiki name, because the trademark owner will not allow us to, and because we want a clean break.
2. The fork needs a release as soon as possible. The minute we have our new name we need to build a release; i.e. within days.
3. Enable extension contributors to post their extensions to the new site without major redesign. They will often be running an older version of TWiki.
4. Users must be able to install plugins they download from twiki.org.
5. Most users are not geeks, and need a non-geeky upgrade solution.
6. Existing investment in user training must not be compromised.

Analysis

100% rebranding will take some time. There are many places where the T* word is used in documentation and, more problematically, in code. For example, LocalSite.cfg on user sites will have it embedded in several places. Peter went out of his way to use the T* word as often as possible.

Short term

There are two realistic scenarios:

1. Complete rebranding - replace the T* name with our new name
2. Partial rebranding - replace the T* name where it is most intrusive e.g. the TWiki web, topic names like TWikiPlugins etc.

Scenario 1 is where we have to start. It means we can have a distinct namespace that can trivially replace T*, something that makes porting extensions easier as well as the core+docs.

How do we support upgrading? The T* word is not used anywhere in the stored data (except in links), so topics should be trivially compatible (famous last words) except where they have linked to the T* web. As mentioned above, configurations are not trivially compatible, but could be easily ported by a simple sed (or equivalent) command that does a global replace. Extensions compatibility is trickier, as most extensions are packaged with the T* word built in, due to the TWiki web being the destination of choice for extension topics. However again I think we can be reasonably smart about this and (1) make the search for the extension topic follow a path and (2) rebrand the main extensions at the same time as rebranding the core.

How do we maintain compatibility? Well, FWIW I (CrawfordCurrie) think this is best done using a one-hit upgrade script. I do not believe there is value in maintaining 100% bidirectional compatibility with T*, for two reasons:

1. It's a lot of work, and easy to get wrong, and when we get it wrong we get it in the neck.
2. Once a user has decided to switch, it has no more value.

Much better to put effort into a really good and flexible and fast and safe upgrade script. Let the TWiki team write the script to reverse the process, should they feel the urge.

Upgrade scripts are not the solution for some of the issues because no script can see the difference between plain text and a web name, for example. However it is fortunate that "TWiki" is such a unique word; it is highly unlikely that a global replace of "TWiki" will hit other words unrelated to the name of the tool. It is also uncommon for user data to use the T* word except for links to documentation (TWikiPlugins etc) and "variables" (%TWIKIWEB%). So a global replace is likely to work quite well.

An area where a compatibility layer is almost unavoidable is the plugin API. If we want users to be able to keep using twiki.org plugins, there are two options:

1. Run all plugins that are newly installed (and might be downloaded from twiki.org) through a 'foswikifier' script, that replaces TWiki::Func calls with Foo::Func calls;
2. Add a compatibility contrib, that simply pipes TWiki::Func calls through to the appropriate Foo::Func calls, perhaps emitting warnings in the logs (that one can turn off) about legacy plugin api usage. Alternatively, the Package::Alias module can be used to make TWiki an alias for the rebranded plugin API package.

Note: a good test for how well we have managed the upgrade process is that the old TWiki installation and the new Foswiki installation are able to share the same data and pub. Foswiki should have plucked all the key config out of TWiki, and relinked the topics in such a way that the TWiki is not broken.

Longer term

Longer term we have some other goals that we would like to address:

1. Make more sense of the webs (TWiki -. System+Documentation, Main->Users) by RenameTheStandardWebs
2. CpanCompatibility
   • KoenMartens 06 Nov: What would we store in CPAN? Surely not the core module (TWiki.pm), but perhaps contribs or plugins?
   • SvenDowideit: definatly YES the core modules - those are key. That way installs will be even easier, as we can leverage all the CPAN installer builders that exist for pretty much all platforms, and we'll have access to many more highly skilled Perl developers.
   • WillNorris: YES! EVERYTHING to be published to CPAN

The Short-term Plan

1. Task109: Rename topics in the documentation set that have the T* word in the name (e.g. TWikiVariables).
   • TopicNameMappingTable lets us know what has been done.
   • Apply the TWikiTerminologyMap to topic content
2. Task113: Rename CSS classes. Only shipped code is done.
3. Task116: Rename javascript classes
4. Item273: rename twiki*.tmpl's
5. Task175: Create a "TWikiCompatibilityContrib"
   • Adds all the TWiki topics to the System web with a link to the correct Foswiki doc
   • Has a "compatibility layer" to support plugins (TWiki::Func must continue to exist)
   • Maps TWIKIWEB to SYSTEMWEB and MAINWEB to USERSWEB (TWiki did the reverse)
6. Manually review and correct copyright texts as appropriate. The code must acknowledge the original TWiki Contributors copyright as well as the new copyright.
7. Create new ApacheConfigGenerator (and this time get the configure config right!)

The longer term plan

Draft, not being worked on

1. Develop (an) upgrade script(s) that work on the following (1) a core source tree (2) an extension source tree (3) an existing TWiki installation.
   1. Replace all occurences of %TWIKIWEB% in core, docs and default plugins with %SYSTEMWEB%
   2. Remap all CSS files, code and docs; local usages of CSS class names and replace with renamed classes.
   3. Rename all topics that include the T* word in the standard webs. Review code (incl. templates and languages) and docs and repair all links to these topics in all nominated webs.
      • Since we are replacing a noun with a noun, it should not be necessary to request re-translation.
      • However there may be a requirement for some languages to retranslate due to the TWikiTerminologyMap
   4. Global-replace links to TWiki web in all topics in all webs, ensuring that the replacement increments the change history of the topic. Note that this script has to avoid breaking full HTMl anchor links to the TWiki.org website.

Please try and keep this plan clean and the page on-topic. It is a key plan that can make or break the fork.