Feature Proposal: How Foswiki deprecates features and APIs

Motivation

We discuss deprecation frequently, but the actual process is only covered piecemeal in code comments, and other casual mentions in the documentation. This proposal is made to document our current practice, and formalize it for future releases.

Description and Documentation

The deprecation process:

1. A Feature or API under consideration for deprecation is proposed through the normal FeatureProposals process.
2. Once the proposal is approved, deprecation is announced for the next major/minor Foswiki release. (a dot-zero release)
3. If the deprecation is urgent, then the next release can use a configuration parameter to allow earlier removal / disabling of the feature.
   • An example of early deprecation / disabling of a feature would be one that has security implications.
4. On the next major/minor release following the deprecation release, the feature can be removed.

Example deprecation process

Normal deprecation

• In release 1.1.4 it was decided to deprecate the blah feature. The "intent to deprecate" can be documented for early notification
• Release 1.2.0 will be announced with the deprecated feature. Documentation will reflect the deprecated status, and documentation can be minimized to discourage use of the feature.
• Release 1.3.0 or 2.0 will have the feature removed.

Accelerated deprecation

• In release 1.1.9 a security related exposure is discovered that requires a change.
• Release 1.2.0 will announce the deprecated feature. Documentation will reflect the deprecated status.
  • The feature will be disabled by default
  • A configuration parameter will be provided to restore the prior operation
• Release 1.3.0 or 2.0 will have the feature removed along with the configuration support.

Active deprecations

Proposals discussing deprecation:

DeprecateAfterAttachmentSaveHandler	Deprecate afterAttachmentSaveHandler	1.1	MergedToCore
DeprecateAllowInlineScript	Deprecate {AllowInlineScript} option in configure	1.1	MergedToCore
DeprecateApacheHtpasswdModule	Deprecate ApacheHtpasswd Module	2.0	MergedToCore
DeprecateAutoAttach	Deprecate auto attachments, and make Update Attachments Plugin a default		DiscardedProposal
DeprecateContextlessURLConstructs	Deprecate Contextless URL Constructs		ParkedProposal
DeprecateEachEventSince	Deprecate Logger::eachEventSince and Func::eachEventSince		RejectedProposal
DeprecateErrorPm	Deprecate Error.pm		RejectedProposal
DeprecateHTTPandHTTPS	Deprecate and restrict VarHTTP and VarHTTPS macros due to security concerns	2.1	MergedToCore
DeprecateInitUserHandler	Deprecate the initUserHandler plugin interface		ParkedProposal
DeprecateSelfRunningExtensionInstaller	Deprecate the executable code in the *_installer files		DiscardedProposal
DeprecateSlashAsRef	Deprecate the use of / for REF in queries, and replace with @		RejectedProposal
DeprecateTheTmplLanguage	Deprecate the TMPL Language		DiscardedProposal
DeprecateUndocumentedSqBracketLinkFormat	Deprecate the undocumented space delimited Square Bracket link format	1.1.4	RejectedProposal
RemoveDeprecatedEmptyDENYRule	Finish off the deprecation of the empty DENY* Rules started back on TWiki	2.0	MergedToCore

Other deprecations found in Tasks web:

• Item12511 - deprecated jquery.metadata
• Item2140 mentions that HTTP_HOST is deprecated
• _ endPoint for REST handlers should be deprecated in favour or the more standard redirectto url param as being used by the other cgi scripts._
• Item12192 "the local jqButton version in NatEditPlugin should go away. I'll also deprecate NATEDIT_THEME now that we've got jquery-ui themes."
• Item12577 Item12650 Item12680 - Various deprecated jquery plugins.
• Item12607 Item12200 - Deprecation of EDITBOXHEIGHT et. al. for 1.2
• Item5215 - Definition list syntax deprecated. ??? (I use it all the time.)
• Item12120 - ApacheHtPasswd module
• Item11365 - Un-deprecate, improve Foswiki::Func::getScriptUrlPath() API
• Item11635 - search script is deprecated
• ... more to go

Deprecations on public APIs recorded in code (with foswiki version of deprecation notice where known)

• Foswiki::Plugin::beforeAttachmentSaveHandler - 1.0.0
• Foswiki::Plugin::afterAttachmentSaveHandler - 1.0.0
• Foswiki::Plugin::endRenderingHandler - 1.0.0
• Foswiki::Plugin::insidePREHandler - 1.0.0
• Foswiki::Plugin::outsidePREHandler 1.0.0
• Foswiki::Plugin::startRenderingHandler - 1.0.0
• Foswiki::Plugin::writeHeaderHandler - 1.0.0
• Foswiki::Plugin::registrationHandler - 1.0.0
• Foswiki::Plugin::redirectCgiQueryHandler - 1.0.0
• Foswiki::Func::registerMETA - 1.1.1
• Foswiki::Func::getRegularExpression - 1.0.0
• Foswiki::Func::getWikiToolName - 1.0.0
• Foswiki::Func::getMainWebName - 1.0.0
• Foswiki::Func::getTwikiWebName - 1.0.0
• Foswiki::Func::getOopsUrl - 1.0.0
• Foswiki::Func::wikiToEmail - 1.0.0
• Foswiki::Func::permissionsSet - 1.0.0
• Foswiki::Func::getPublicWebList - 1.0.0
• Foswiki::Func::formatTime - 1.0.0
• Foswiki::Func::formatGmTime - 1.0.0
• Foswiki::Func::getCgiQuery - 1.0.5
• Foswiki::Func::readTopicText - 1.0.7
• Foswiki::Func::saveTopicText - 1.0.7
• Foswiki::Func::addToHEAD - 1.1.0
• Foswiki::Func::searchInWebContent - 1.1.1
• Foswiki::Func::getDataDir - 1.0.0
• Foswiki::Func::getPubDir - 1.0.0

-- Contributors: GeorgeClark, CrawfordCurrie

Discussion

Sounds very sensible. From a technical perspective, it would be helpful if there was a standard way to handle the deprecation in the configuration. For example:

# ---+ Deprecated Features
# See Foswiki:Development/DeprecationProcess for more information about the Foswii deprecation process.
# **BOOLEAN**
# HTTP and HTTPS macros provide information that is more controllably obtained from the ENV macro. See Foswiki:Development/DeprecateHTTPAndHTTPS for details.
$Foswiki::cfg{Deprecated}{HTTPandHTTPS}{Enable} = 0;

-- CrawfordCurrie - 21 Jun 2014

Removed the deprecated AllowInlineScript for 1.2.

-- GeorgeClark - 23 Jun 2014

Once a feature is marked deprecated, we should immediately offer a way to migrate away from using this feature, so that users have a chance to act upon the announcement and know their system is future-proof.

I just mention this as in the past we had features being deprecated for a long time but don't gave users a migration path to convert their system to a state that was not using this feature anymore.

Most prominent example is empty strings in ACLs that were deprecated for a very long time already with no alternative in sight.

So part of the deprecation process must be a specification of a migration path including an "overlap" period where both - the deprecated feature and a migration or replacement feature - are available.

-- MichaelDaum - 23 Jun 2014

Agreed. Another one is the afterAttachmentSaveHandler. I did a quick search of extensions in svn and it's still used in a significant number of extensions. So in this case, unless we make an effort to update the extensions ourselves, the API should probably remain.

-- GeorgeClark - 23 Jun 2014

Collated all the deprecation knowledge into the list in the OP.

I'm of a mind to say that the deprecation notice has been issued for all the plugin handlers (deprecated handlers are reported in InstalledPlugins). Foswiki::Func functions are recorded as deprecated in the API doc and in the release notes, so these can also be considered as having been notified. Thus I believe we should remove these APIs in 1.2.0

-- CrawfordCurrie - 28 Jun 2014

For the extensions that this project forked and don't have a maintainer, we need to take responsibility to do the update to remove the deprecated API. The base of extensions that no longer work is creeping upwards as things like perl qw() and defined deprecations happen. Removing all the deprecated API's will probably kill a bunch more extensions.

-- GeorgeClark - 28 Jun 2014

Changed this topic from a FeatureRequest to DeveloperDocumentation. And will link it to the DevelopersBible.

-- GeorgeClark - 18 Jul 2015

Commenting is disabled while not logged in