Making extensions upgrade-safe

Core code already has a strong review policy, and an explicitly review period in which many eyes help avoiding non-backwards compatible changes. This culture comes from a long tradition in the Foswiki project: to protect previous investment by our users. Core extensions follow this process, and they are fine.

Non-core extensions, on the other hand, do not have a strict development process. This is good, and it's the reason why so much innovation happens in the extentions front. There are a lot of core features that were first introduced by extensions and then moved into the core. Non-core extensions are also a very good selling argument for Foswiki, and for several Foswiki use cases non-core plugins become a core part of the sollution for those users. That's why we must be concerned about handling smooth upgrade paths for extensions. Once a user installed an extension and started using it, installing the next version of that extension must not break what the user already built using it.

Let's try to document common cases of non-backwards compatible changes in extension development and ways to workaround them.

%MACRO% moved to OtherPlugin

• Causes
  • %MACRO% makes more sense, or works better, with OtherPlugin
  • ...
• Suggested workflow:
  • Move %MACRO% from MyPlugin to OtherPlugin
  • Make sure %MACRO% keeps a backwards-compatible interface, e.g. it supports the same parameters, and works in the same ways as before
  • Make MyPlugin depend on OtherPlugin by declaring a dependency in lib/Foswiki/Plugins/MyPlugin/DEPENDENCIES
  • Coordinate so that new versions of MyPlugin and OtherPlugin are released simultaneously

%MACRO% must be removed

• Causes
  • %MACRO% is already implemented by other plugin
• Suggested Workflow:
  • ...

-- AntonioTerceiro - 09 Nov 2010

Comments and discussion

Hello all, please help in documenting issues above. Thanks.

-- AntonioTerceiro - 09 Nov 2010