Plugin API Policies

Introduction

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 Applications.

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 Foswiki::Func, Foswiki::Meta, and Foswiki::Sandbox
3. The subset of $Foswiki::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 Foswiki. We visited all the published plugins during Foswiki development 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 Foswiki 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

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 Foswiki 1 will still be available in Foswiki 3, but might be removed after that.
2. Functions documented in Foswiki::Func and Foswiki::Meta have the same deprecation policy (retained for at least 2 major releases after deprecating release)
3. Core functions called by extensions 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.
4. The retention period can be extended if many extensions are still not able to change to a newer function, even with assistance from the community. Extension authors should request this through the FeatureProposals process.

Developers will make every effort to ensure that extensions 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 extension authors in making the necessary changes.

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. You can't even rely on their being files on disc. Use the APIs to manage the database.
• While your plugin will be be passed embedded meta-data in topic text where that is documented, it will be removed at some point and you are strongly recommended not to use it. Interact with the Meta object passed to most handlers instead.
• You cannot rely on the Foswiki::Plugins::SESSION object. It will disappear at some point.
• Additional APIs may be defined in Contribs. These may claim to be "official" or "awaiting merge to the core", but you still should treat them with extreme care. Use these APIs-in-waiting at your own risk.

Ensuring plugin reliability

Violating these policies does not mean that a plugin won't work with earlier releases. 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. 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 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 extension author should be aware of.)

Extension Maintenance Guidelines

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

So extension authors are encouraged to maintain their code so that it runs 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 earlier releases.

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.

Note that the auto-porter target that supports porting to TWiki in BuildContrib may be extended to support targeting different production releases of Foswiki, should it become necessary (right now it isn't).