Tags:
plugin1Add my vote for this tag create new tag
view all tags

Why "Pluggable" is Harmful

During the development of TWiki's DakarRelease and the planning of EdinburghRelease I've (too) often read the word "pluggable" which is thought to be a solution of many problems, and I myself am guilty of having sung that tune loudly. So I'd like to issue a word of warning before we are starting daydreaming too much.

While I agree that a modular design is a good thing and does allow fast and stable implementation of features in isolated components, we should keep in mind that these components need to work together in any conceivable combination, in any real-life TWiki installation.

There are a couple of gotchas we need to take care about. We should not abandon modularization, but we must not postpone thinking about the prerequisites any longer.

Plugins and the Readonly TWiki Web

Independent of Pluggable, there is the idea of making the TWiki web more and more readonly, to allow for easier version upgrade: Just keep your own topics, and take the TWiki web (with the TWiki documentation in it) from the new distribution. Neat.

It only clobbered a lot of my plugin settings, when I unzipped the TWiki web from the 4.0.1 distribution into my life 4.0.0 TWiki. My fault, of course. I shouldn't have believed that the TWiki web is readonly right now.

And then, if plugins are changing TWiki behaviour, it might be necessary that the documentation takes care for that. Currently in Dakar's ChangePassword and a couple of other pages we have:

Note to administrator: This form applies only if TWiki uses a {PasswordManager} that supports changing passwords (e.g. TWiki::Users::HtPasswdUser). Otherwise replace this topic with a note describing how to change the password in your organization). See TWikiUserAuthentication for more information.

Isn't that ugly? Hey, administrator! We might have told you that the TWiki web should be readonly, but on the other hand we want you to figure out how your password manager works, and to overwrite this topic with whatever you've found out. Good luck!

Requirement
Plugins need a way to not only drop-in their code, but also their documentation.

Plugin Variables and TWikiVariables

I've just recently deployed a TWiki in our company. People are starting to write their own pages, which is The Right Thing in my opinion. And they are asking questions:

In your topic, I found a list of actions. This looks nice. All you wrote in your topic is %ACTIONSEARCH{...}% - but how does this variable work? I can't find it documented in TWikiVariables, and a search didn't reveal anything useful!

Well, it isn't documented in TWikiVariables. And he didn't find it in WebSearch because with his first attempt he did a search only for the current web (which happened to be my project web, and not the TWiki web), and with his second attempt he gave up too early when scrolling. He would have probably succeeded if the letter 'T' wouldn't be so late in the alphabet, or if it were called the AATWiki web.

Requirement
Plugins need a way to make their variables' documentation easily found without knowing the plugin name in advance (more about that in CleanUpTWikiVariables).

Plugin Dependencies

Sometimes a Plugin wants to use a feature which is available in another plugin. But if all plugins are optional: Do we need to check plugin prerequisites in addition to CPAN prerequisites? And what about independent development - how do we make sure that we find the right versions of the plugins we're depending on?

In TWikiRelease04x00, we've learnt that this isn't easy: 4.0.1 contained a new version of JSCalendarContrib which didn't work with the version of ActionTrackerPlugin available at that time. A "correct" ActionTrackerPlugin has been available from SVN, so the SVN testers couldn't notice the problem - it was up to the customer to find out.

Requirement
We need a standardized and documented mechanism to check for compatible versions of the plugins/contribs a plugin relies on. Either CPAN-like or SVN revision, but all plugins and contribs need to know how it's to be done, and to comply.

Plugin Interferences

This is a problem of all three of implementation, testing, and documentation. Sometimes a plugin gets best value if combined with another plugin, but must work without it as well ("pluggable" means you can plug it out, doesn't it?). The example I've always in mind are the TablePlugin and the EditTablePlugin. In this particular case the problem is "solved" because both plugins are shipped with the distribution, but "pluggable" means you have a small core, doesn't it?

So where's the problem? I've been asked:

If I want to use both %TABLE% and %EDITTABLE% - do I have to obey a certain sequence? Are there restrictions?

Do I? Are there? The documentation wouldn't tell me. I can try it out, and I'm leaving it as an exercise to the reader to figure out the differences. The more important question: If it isn't documented, is it guaranteed that it will work as today in the next release?

Urgent Wish
Plugin authors ought to look at their environment - are there any other plugins in the neighbourhood?

Plugin I18N

The DakarRelease made an interesting step towards internationalisation of the user interface. However, the I18N framework is still strictly centralistic: There's one monolithic master catalog from which the translations are derived.

Requirement
We need a mechanism for pluggable components to add their strings, and to distribute their translations together with the pluggable component.

-- Contributors: HaraldJoerg

Discussion

There is a way to specify dependencies between plugins and enforce them if the plugin is installed using the BuildContrib generated install script.

-- RafaelAlvarez - 17 Feb 2006

As one of the main sinners chanting "pluggable", I would like to clarify something. The terminology may be confusing, but by "pluggable" I don't mean "by using a plugin". I mean something more in line with "pluggable implementation", much like what was done for the password management. To achieve this in a proper way, "extension" points need to be identified, a very decoupled API needs to be defined and very very decoupled implementation need to be implemented.

At the end, my vision is to have a "micro-kernel" coordinating all the "pluggable" implementations of the modules, plus plugins adding "non-core" functionality.

-- RafaelAlvarez - 17 Feb 2006

I agree on BuildContrib and the need for a decoupled API. But I dare to emphasize, again, that almost all my requirements above are talking about documentation and not implementation.

Taking your example, password management: I agree that the implementation is what we should have in mind: A plain core, with a set of drop-in replacements. However, the documentation falls short, in leaving it up to the administrator to document what he has selected in bin/configure.

Quoting Dakar's TWikiInstallationGuide:

  • Clear admin notes - some pages are meant to be customized after choice of authentication - check and update these topics (remove notice):
    • ChangePassword
    • ResetPassword
    • ChangeEmailAddress
    • TWikiRegistration fields can be customzied to the needs of your organization
    • TWikiAdminGroup

Now consider a micro-kernel with lots of these "pluggable" implementations. And feel with the poor admin who has not only to choose between all of them, but also to update half of the TWiki web, to properly reflect his choices. And while LocalSite.cfg isn't touched when upgrading TWiki, the TWiki web is - so it will be a hassle for every new version.

And we are going towards a readonly TWiki web, aren't we?

-- HaraldJoerg - 17 Feb 2006

The TWiki web setup as it is currently has both pros and cons. The pro is that since it is editable, I can re-write large sections of documentation on my install to make it more user friendly and/or specific to my company. The con is that upgrading TWiki means backing up all those files and then finding some way to merge them with the newer versions (which pretty much ends up happening manually).

Making TWiki web read only would just reverse the pro/con scenario. Ideally the documentation would be good enough that this wouldn't be an issue, but lets be real--it takes time to improve documentation and what I consider an improvement, you may not like. For this reason I don't think moving to a read only TWiki web is a good idea, besides, it goes against the wiki way.

So if read only isn't a good solution, how do we improve the documentation merging at upgrade time? Maybe a programmer could come up with some means of comparing revision histories (using date/time stamps if they exist) and automagically offer a merged document. It wouldn't be ideal and would probably still require some manual tweaking, but it might involve less work for the admin who has to merge different doc versions.

-- AmandaSmith - 21 Feb 2006

Rafael has stated my view of "pluggable" exactly. I see any class in TWiki as potentially pluggable, which is why I have sought to encapsulate them wherever possible.

When I need to customise documentation locally, what I tend to do is either create custom topics in the TWiki web, or create a whole new documentation web and copy the bits of documentation across that I think are healthy.

The current TWiki documentation suffers from the same disease as the code itself. Because TWiki was once a monolith (as recently as Cairo release) modularising documentation has never been an issue before. Now it is, and a concerted effort to modularise documentation is required. But it's a huge job, and many people would prefer to customise their local docs than contribute effort back to the community (sorry, Amanda, but you know who I mean).

To make my position clear, here's how I see it working in the future:

  1. The documentation of the core is iteratively reduced over time.
  2. Documentation for pluggable components is kept separate, by shipping the components themselves as contribs.
  3. The BuildContrib has the means to modify docs during an install; probably limited to adding a %INCLUDE to index topics.
  4. Plugins configuration variables are taken out of the TWiki web and into configure
Note that we are already in the situation that core documentation does not document the system, because (for example) plugins add many variables to the system. Currently these are only documented in the plugin doc, which is extremely user unfriendly (users don't care that something is a plugin)

The ultimate goal is a TWiki that is comprised of just one or two code modules and one or two core documents, which themselves are just indexes to the wider documentation set. Which gets me thinking; see PluggableDocumentationArchitecture.

-- CrawfordCurrie - 21 Feb 2006

dammit Harald - I agree with everything you are really saying, except for the topic name, which i see as scare mongering. all the REQUIREMENTS you list above are on my list too.

-- SvenDowideit - 21 Feb 2006

BasicForm
TopicClassification BrainstormingIdea
TopicSummary For "pluggable" to be a good idea, we need a foundation
InterestedParties

RelatedTopics

Edit | Attach | Watch | Print version | History: r6 < r5 < r4 < r3 < r2 | Backlinks | Raw View | Raw edit | More topic actions
Topic revision: r6 - 2006-02-21 - SvenDowideit
 
  • 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-2024 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.