dev_essential1Add my vote for this tag plugin1Add my vote for this tag process1Add my vote for this tag twiki_community1Add my vote for this tag create new tag
, view all tags

Plugins API Policies

It's important that authors of Plugins are able to work within an environment without shifting ground rules. Otherwise, people end up having to recode their plugins for every release, something which needs to be avoided wherever possible.

Note that we are talking about Plugins here - extension modules that work within the Plugins Environment, and do not use any internal core functions or rely on unpublished APIs. We are not talking about Contrib/AddOn modules, which by definition extend the core functionality. We are also not talking about TWikiApplications. TWikiApplications authors should refer to the TWikiApplicationStabilityPolicies.

The Plugins Environment

The environment that can be relied on by Plugins authors is defined as follows:
  1. Handlers defined in EmptyPlugin,
  2. Methods defined in TWikiFuncDotPm, TWikiMetaDotPm, and TWikiSandboxDotPm
  3. The subset of $TWiki::cfg that the plugin has defined itself using SpecifyingConfigurationItemsForExtensions.

This is a fairly robust spec, and it's hard to see a need to work around it in TWiki-4. We visited all the published plugins during TWiki-4 to ensure that as many as possible were caught by this spec. The spec is of course incomplete, as it doesn't speak to how the META is organised in a META object (FORM, FIELD etc), but it isn't bad.

The goal of TWiki development is to maintain a stable API. That means that if we publish something in the API, then there are certain guarantees of stability around that API. Specifically, we won't banjax your plugins by changing the APIs faster than you can keep up with.

Extension policy

The various APIs may be extended from time to time, and new methods introduced that make old methods redundant. The old methods will be maintained for a time (see Deprecation policy). In many cases, the introduction of a new method that replaces an old one may result in a drop in the efficiency of the old method. Plugins authors will be warned of this in release notes, and given support in recoding for the revised API. Nevertheless, we will keep the number of deprecations to an absolute minimum.

Deprecation policy

This has never been officially stated before, but here we go. The official deprecation policy is this:
  1. Handlers documented in EmptyPlugin will be maintained for at least 2 further major releases after the release they are deprecated in. So a handler deprecated in TWiki-4 will still be available in TWiki-6, but might be removed after that.
  2. Functions documented in TWikiFuncDotPm and TWikiMetaDotPm have the same deprecation policy (retained for at least 2 releases after deprecating release)
  3. Core functions called by plugins outside of the official APIs are subject to change without notice. However the core developers will make every effort to ensure the community is warned well in advance.

Developers will make every possible effort to ensure that plugins that are written to observe the documented API will continue to work without requiring code changes or, if such code changes are unavoidable due to shifting architectural constraints, will support plugins authors in making the necessary changes to the extent of providing code porting support.

What you should not rely on

  • You cannot rely on files on disk remaining in the same formats or the same places. You cannot rely on the current directory structure. Use the APIs to manage the database.
  • You cannot rely on $TWiki::cfg, other than for the pieces your plugin defines for itself. For all others, use the accessors define in TWikiFuncDotPm
  • While you can rely on your plugin being passed embedded meta-data, you cannot make assumptions about the total embedded meta-data. New meta-data fields may be added without warning, so your plugins should be robust to such changes.
  • You cannot rely on the TWiki::Plugins::SESSION object. It will disappear at some point.
  • Additional APIs may be defined in Contribs, such as the FuncUsersContrib. Use these at your own risk.

Ensuring plugin reliability

Violating these policies does not mean that a plugin won't work with Dakar. Just because it happens to work, however, is not a reason to ignore the policies. Violating the policies make the plugin far less likely to work in future versions, especially with changes intended to improve performance.

In addition, it's extremely important that all extensions -- indeed, all perl modules -- use the use strict; pragma. Far too many don't, primarily ones that were written for Cairo. Authors are strongly encouraged to use this pragma and to fix any errors that result from using it. If there are errors, that doesn't not mean that the pragma is causing them: it's catching them.

(Strictly speaking this latter bit has nothing to do with API, of course, but this is an important issue that every plugin author should be aware of.)

Plugin Maintenance Guidelines

It's impossible to force a policy for plugin maintenance on plugins authors, even if we wanted to. However your attention is drawn to the fact that many site owners do not upgrade a TWiki right away for various reasons. At the same time, these owners would like to have access to the latest Plugin technology.

So Plugins authors are encouraged to maintain Plugins so that they run on the current production release and one release back from the same archive i.e. an admin downloading "XyzPlugin" should be able to do so knowing that the code therein will run with TWiki-3 or TWiki-4. HandlingCairoDakarPluginDifferences shows how to maintain Plugins that are Cairo and Dakar compatible.

This can be achieved in (at least) a couple of ways:

  • by using the same code base and, if needed, conditionally selecting code sections for each core version. This is the preferred method if the code differences are small.
  • by packaging two versions of the plugin in the same archive and selecting the correct code to install at install time.

If you can't or don't want to do either of these, then at least seriously consider maintaining the previous version as well as the current one and clearly mark which version is for which release.

-- Contributors: CrawfordCurrie, PeterThoeny, MeredithLesly

Discussions about the plugin api policies have been moved to PluginsApiPolicyDiscussion

Edit | Attach | Watch | Print version | History: r74 < r73 < r72 < r71 < r70 | Backlinks | Raw View | Raw edit | More topic actions
Topic revision: r74 - 2006-12-02 - HaraldJoerg
  • 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.