Handling updates and new default features

[mboynes]

Description

I admit there's some level of FUD in this topic, but I'll try to keep it as action-focused as possible.

Updating Alleyvate on a site carries a level of risk. Each update will (almost certainly) include new default features, which will add, remove, or modify some aspects of WordPress core. These may be things about WordPress that a site uses, whether we realize it or not. As a for-instance, say the plugin disables "sticky posts" at some point in the future. As far as I know, we don't use that anywhere, but it's possible one of our clients does leverage that feature.

All this to say, every Alleyvate release is (again, almost certainly) a "breaking change" for WordPress. Below are some assorted recommendations that come to mind for me. Let's discuss these and others to codify some process for updating Alleyvate on a site.

1. Alleyvate must follow a proper (semver) release cycle, and sites must only install releases (never install via the main branch).
2. Releases must include a detailed changelog which includes an upgrade guide. The upgrade guide should call out specific things to check and include copy-pasteable code to disable the feature.
   • Example: When Feature: Disable Comments #35 is released, it should recommend that a developer check the comments table to be extra certain that a site doesn't use, and hasn't ever used, comments. It should also include a note "To opt out of this feature, add add_filter( 'alleyvate_load_disable_comments', '__return_false' ); and/or add_filter( 'alleyvate_load_disable_trackbacks', '__return_false' ); to your codebase."
3. Alleyvate must not be updated blindly on a site.

[dlh01]

My conception of Alleyvate, at least at the beginning, was that landing something in Alleyvate was tantamount to writing it in the company handbook. Teams would have to put in effort to opt out, rather than allowing themselves to wait to opt in.

I would definitely be on board with using semver releases, but I would have assumed that only changes to Alleyvate's own API might warrant a major release — for example, if we changed the alleyvate_load_{$handle} filter to alleyvate_load_feature_{$handle}. Adding a new feature wouldn't constitute a breaking change because it represents, in a sense, a company-approved bugfix for something that was always wrong on the site before.

To that end, I really like the idea of a detailed upgrade guide with the suggestions you mentioned so that the actual effort for teams to opt out is minimal ("you might want to opt out of this feature if...").

[mogmarsh]

We need to identify where these opt-out filters are going to live. I added a filter here to disable the Apple News Push feature, but I don't see any other filters in features yet. I wonder if we should centralize and standardize this - maybe somehow in the Feature interface or in the load.php file? - maybe we apply_filters to the $features array before looping?

[dlh01]

I had assumed that "opting out" in this case meant disabling the feature using one of the filters here:

wp-alleyvate/src/alley/wp/alleyvate/load.php

Lines 41 to 57 in f46bfdb

	/**
	* Filters whether to load an Alleyvate feature.
	*
	* @param bool $load Whether to load the feature. Default true.
	* @param string $handle Feature handle.
	*/
	$load = apply_filters( 'alleyvate_load_feature', $load, $handle );
	/**
	* Filters whether to load the given Alleyvate feature.
	*
	* The dynamic portion of the hook name, `$handle`, refers to the
	* machine name for the feature.
	*
	* @param bool $load Whether to load the feature. Default true.
	*/
	$load = apply_filters( "alleyvate_load_{$handle}", $load );

If features want to provide granular filters as well, that might not be so bad, but I'm unsure how it would be standardized.