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.
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?
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:
- The documentation of the core is iteratively reduced over time.
- Documentation for pluggable components is kept separate, by shipping the components themselves as contribs.
- The BuildContrib has the means to modify docs during an install; probably limited to adding a %INCLUDE to index topics.
- 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