Deprecation/Graduation policy for experimental APIs proposal

[alexflorisca]

We need to formalise a policy around the experimental APIs for WooCommerce Blocks (and WooCommerce at large). This is important as we become the default Woo checkout experience, more developers will make use of our APIs and we need to make sure there is a plan in place to keep this stable.

Lessons from Gutenberg

The first thing I looked at is what Gutenberg does which I’ll summarise here

• There is tension between keeping backwards compatibility (nature of WP) and the experimental nature of Gutenberg.
  Almost everyone agrees there needs to be a compromise between the two.
• They’re finding it difficult to decide what to do with experimental APIs already in Core. It seems it was a mistake to introduce experimental APIs in WP core.
• Gutenberg has a new lock & unlock API that has been working well.
• They use a 2 year deprecation time window with a deprecation message incentivising users to use new API

Lessons from Woo

Woo Core is working on bringing all its feature plugins in house and shifting the mindset from “everything must be stable” to allow for some experimental work directly in Woo Core. This is re-assuring as we tend to have a lot of experimental interfaces, and probably more to come as the developer requests come in. They should be able to support us developing work behind feature flags once we move to core.

Since the merge of WooCommerce Admin there has been a precedent set for developing experimental features behind feature flags. We have seen this now with HPOS and the new product editor that are both under active development. I think it’s important to step away from the idea that WooCommerce Core cannot contain experimental work.

Proposal

1. Graduate all experimental features to stable before the default release

We need to provide a stable base from which to build on. Most of our experimental extensibility points have been around for a while and I would consider them stable. This was also a learning from Gutenberg, they found it difficult to maintain a lot of experimental APIs once they had been introduced into WP Core. Although saying that, it doesn’t mean we shouldn’t experiment, and this is a good opportunity for us to review our experimental interfaces before we become default.

2. Use the lock / unlock API for experimental filters, slots and methods on the front end.

The lock / unlock API from Gutenberg allows for encapsulation of private information inside public objects. This is a great way, for example, to export a filters object and encapsulate any experimental filters inside it. The consuming third party developers will get only the public filters by default, and must explicitly opt in for experimental filters. This keeps the public API stable, while allowing the introduction of experimental features.

The details of this need to be fleshed out a little more and I’m happy to get a try/ PR up to prove this concept.

3. Explore using the Automattic\WooCommerce\Internal namespace for experimental PHP filters and actions

@ObliviousHarmony wrote about this

When it comes to PHP code there is an Automattic\WooCommerce\Internal namespace that is not considered part of the public API. Here you are free to make any PHP-specific changes without concern that anyone should expect them to be stable.

This needs a little more discussion and I would be keen to hear from the PHP gurus on this.

4. Use a 2 year deprecation window.

This is a bit controversial as initially we said around 6 months. But my thinking here is

• We want to align with Gutenberg on this.
• We will see a large increase in developers integrating with the Cart & Checkout blocks (hopefully!) and we want to provide as stable platform as we can for them. Asking them to make significant code changes in 6 months time, after maybe a few months of development from their side, is a bit unfair to me.
• It will make us think very carefully about what we make public!

5. Review experimental features every 3 months.

I think we need to be a little flexible when graduating experimental features, as not all features are created equal. It’s difficult to say something like “Once an experimental feature has launched, we will graduate it in 6 months”, because there are a lot of variable that will determine what eventually happens to that feature. It may be axed, graduated or fleshed out, and there’s no one size fits all. What I propose is to review all our experimental features every 3 months and determine what to do with them (much like we do right now before WC Core releases).

Whad’a think? What have I not thought of? What does the community think?

Some useful links

Lock an unlock functionality in Gutenberg
Original GH PR about what to do with experimental APIs
Available Extensibility Interfaces for the Cart and Checkout blocks

[opr]

Thanks for writing this @alexflorisca!

1. Graduate all experimental features to stable before the default release
   We need to provide a stable base from which to build on. Most of our experimental extensibility points have been around for a while and I would consider them stable. This was also a learning from Gutenberg, they found it difficult to maintain a lot of experimental APIs once they had been introduced into WP Core. Although saying that, it doesn’t mean we shouldn’t experiment, and this is a good opportunity for us to review our experimental interfaces before we become default.

I don't agree that we should graduate all cases actually, for example the slot fills. These can be replaced by extensions rendering their own blocks as children of a specific block. So, maybe keep slot fills experimental with a view to deprecating them in 2 years?

The lock / unlock API from Gutenberg allows for encapsulation of private information inside public objects. This is a great way, for example, to export a filters object and encapsulate any experimental filters inside it. The consuming third party developers will get only the public filters by default, and must explicitly opt in for experimental filters. This keeps the public API stable, while allowing the introduction of experimental features.

I don't know if this would work on the current setup of registerCheckoutFilters though would it, since the filters you want to apply are set up as an object, or are you thinking of something else?

Use a 2 year deprecation window.

Seems OK to me. Alignment with Gutenberg is always a nice idea. Two years should long enough for us to advertise the changes and for developers to pick up on them and update their code.

5. Review experimental features every 3 months.

Seems OK, but my gut feeling is this may be a little too frequent, would 4 or 6 months be better? Whichever we choose, this timeframe could also be used to review the points that have been deprecated for more than 2 years, and to open an issue to remove them.

[alexflorisca]

I don't agree that we should graduate all cases actually, for example the slot fills. These can be replaced by extensions rendering their own blocks as children of a specific block. So, maybe keep slot fills experimental with a view to deprecating them in 2 years?

Yep good point here, happy to keep slot fills as experimental for the time being and encourage people to create inner blocks instead. We can also review everything properly and make a final decision as to what is to be stable and what is to remain experimental.

I don't know if this would work on the current setup of registerCheckoutFilters though would it, since the filters you want to apply are set up as an object, or are you thinking of something else?

I was thinking that we store the checkout filters in an object here. And part of that object could be locked with any filters that are experimental.

For example, say we had a __experimentalCheckoutTitle filter and all filters are stored as props on checkoutFilters We would do something like

lock(checkoutFilters, __experimentalCheckoutTitle);

I haven't actually tried to see if this works yet, but that's my thinking anyway. it's also worth mentioning that this is still an experimental API (it comes from the @wordpress/experiments package) and so I'm having second thoughts wether it's actually a good idea to transition to this so soon.

Seems OK, but my gut feeling is this may be a little too frequent, would 4 or 6 months be better? Whichever we choose, this timeframe could also be used to review the points that have been deprecated for more than 2 years, and to open an issue to remove them.

Happy with a 6 month review yep. As long as they get scheduled in, that's what we've been missing so far.

[opr]

The checkoutFilters you mentioned is actually an object of namespaces, so that won't work.

Seems like lock/unlock is used to output two different objects based on whether it's locked. The locked one contains the "public" properties, and the unlocked one contains the public and private ones. We don't export any objects containing filters where we could have public or private ones.

I would love to be able to use it but I really don't think it's applicable here unfortunately, if you do get time to take a look it would be good to confirm though.

[opr]

@alexflorisca I misunderstood the lock/unlock API, but I think my comment above is still relevant due to the way filters are applied, they're not presented as part of an object. Still looking into it would be good when you can!

[joshuatf]

Are we talking about the checkout filters in here?

If so, with the lock/unlock API, I believe typically we'd look at locking the registerCheckoutFilters. If this was stable and we were instead wanting to lock down a specific property, prefixing with __experimental is mostly the way I've seen this done in Gutenberg.

[alexflorisca]

The registerChekoutFilters function is stable, I was thinking we can lock specific properties on the checkoutFilters variable that holds all the filters, so that if someone tries to do this

registerCheckoutFilters( 'example-extension', {
	cartItemClass: modifyCartItemClass,
} );

and cartItemClass is an experimental filter, it would be locked, and this code would throw an error letting the user know they need to unlock this object to use experimental filters.

I'm yet to try this though, I've been on extended AFK and just got back, so I will give it a go. I think there are limitations with this as Thomas pointed out so it may or may not be useful.

What might be more useful is to lock/unlock experimental APIs on the blocksCheckout object. For example, there are currently 4 experimental slots available, which could benefit from this.

The idea here is that either we replace all uses of frontend filters with the lock/unlock API, or we stick to using experimental as a prefix. I wouldn't want to have both as that would just confuse things. I will do a spike for this if time allows and see how it could work.

[senadir]

We need to provide a stable base from which to build on. Most of our experimental extensibility points have been around for a while and I would consider them stable.

My problem with this point and the reluctant nature of it is that we don't have strong feedback about if they're being used or not. The problem with stability isn't that it will trigger errors, but will it accommodate the several possible use cases, and will the current approach have performance limitations (which we can't fully test). Sadly, it's a bit hard to get people to use experimental stuff, so we don't have strong feedback about them yet.

The concept of limiting certain data stores actions is to prevent abuse, which is hard to detect until it happens.

I also agree that a 2 year time window is good, a bit on the long side, but still fine. Exception can be made if we found out an extensibility point can be abused to the advantage of a plugin over the others.

[senadir]

Overall I think we should go ahead and review our existing experimental ones and start graduating them as it make sense. The graduation policy I suggest is:

• Do the 2 year policy if the new solution is better future proof, faster, or more ergonomic.
• Consider a shorter, case by case, for APIs that prove to be over-powered or over-permissive that it risks the level playing field or consistency of a store (ideally after providing an alternative).
• Possibly a much shorter, no wait time for extensibility APIs that might have security risks that can't be patched (unlikely to have that).

[barryhughes]

3. Explore using the Automattic\WooCommerce\Internal namespace for experimental PHP filters and actions

@ObliviousHarmony wrote about this

When it comes to PHP code there is an Automattic\WooCommerce\Internal namespace that is not considered part of the public API. Here you are free to make any PHP-specific changes without concern that anyone should expect them to be stable.

My understanding of the current situation is that, just because an action (or filter) is triggered from within the internal namespace, that doesn't implicitly mean it is considered off-limits for third party code. Instead, they are also part of the public API surface.

I'm a little unsure if we really need or want experimental/private hooks but, if we do, couldn't they live anywhere (including locations outside of the internal namespace)?

[ObliviousHarmony]

My understanding of the current situation is that, just because an action (or filter) is triggered from within the internal namespace, that doesn't implicitly mean it is considered off-limits for third party code. Instead, they are also part of the public API surface.

Yes, that's what we decided originally. The justification was that we're relying explicitly on WordPress' filtering and action system to create hook points for code to consume. It seemed anti-WordPress to say that a "private" hook might exist. We can create our own subscription class for internal use if we want to utilize hooks without relying on WordPress' here.

[joshuatf]

1. Graduate all experimental features to stable before the default release

While this sounds ideal, I'm in agreement with @opr on this point. There are just too many factors to consider here and while we can strive to make the "base" API stable, the lifecycle of code almost guarantees that we will have some newly implemented features that have not yet had time to mature.

Also, while it might be implicitly understood, I think it's worth noting that any experimental APIs that were prefixed with "experimental" should be aliased to their non-experimental counterparts for the deprecation period.

2. Use the lock / unlock API for experimental filters, slots and methods on the front end.

I'm on board with this 👍

3. Explore using the Automattic\WooCommerce\Internal namespace for experimental PHP filters and actions

Noted above but confirming that any hooks exposed inside of this namespace are public API and considered fair game. Using pub-sub patterns or internal registries, depending on the use case, is favorable over hooks if you don't want it externally consumed.

4. Use a 2 year deprecation window.

I want to push back on this point given how long a window this is, but It will make us think very carefully about what we make public! is IMO the strongest case for this. If other teams are on board, I don't mind aligning on this window.

5. Review experimental features every 3 months.

Sounds great! I've seen Gutenberg's threads on reviewing experimental features. I'm wondering:

1. How much of this process can we automate? Automatically detecting experimental features/hooks will go a long way in making this process easier to manage.
2. Given some teams have different release and sprint cycle cadences, I wonder how each team will actually execute this review. As part of a planned cooldown? Alongside cycle work? My fear with these kinds of things is always that they get swept under the rug in favor of "more pressing matters."

[joshuatf]

Use a 2 year deprecation window.

Just noting another comment on Slack from Mothra that this sounded like a lengthy period of time and preference would be for 1 year, but also not overly opinionated on this. If this is what other teams are happy with, then we should align on the same timeframe.

Use the lock / unlock API for experimental filters, slots and methods on the front end.

I already see some confusion on Slack (and seems like some question above in this thread) on when to use each type of guarding mechanism. Once we settle on a final policy, I think a flow chart for introduction of new APIs as well as one for how deprecation should be handled will make this much easier to follow.

[alexflorisca]

The 2 year deprecation window came from Gutenberg so we are just looking to align with what they're doing. I would also be happy with a 1 year window if that's the standard in WC, or if that's the standard we want to adopt in WC. Given WC supports last 2 WP versions, that's about a year, so it makes sense to have the deprecation window be roughly aligned with that too.

As for the confusion around the lock/unlock API, I made a comment above that might clarify at least my thinking around it.

[PanosSynetos]

As long as we give enough time and we clearly define what is about to graduate, I'm fine with "any" decision (I tend to agree that 2 years seem like a long time).

We wouldn't want 3PDs and/or other internal teams maintaining extensions, to be caught by surprise.

[nerrad]

A few suggestions for moving this forward:

• Has the lock/unlock API been experimented with yet to test feasibility in the WooCommerce codebase?
• Some discussion has happened in here. Maybe the next step would be to summarize where there appears to be agreement and summarize any changes to the original proposal.
• I think there is a benefit in surfacing this discussion to a larger audience via the blog on developers.woocommerce.com. You can include a summary of the proposal in that (or point to a summary in this discussion).

[alexflorisca]

Has the lock/unlock API been experimented with yet to test feasibility in the WooCommerce codebase?

I tried it very briefly for the front end filters we have a while back but it won't work with our current implementation. There is still a use case of using it to differentiate between public and experimental actions and selectors available on our wp.data stores, but I haven't looked into this yet. My instinct here is that it's only worth changing to this API if we can do it consistently throughout the codebase. Having a mixture of __experimental prefixes for some things and lock/unlock api for others seems like it would complicate things for devs. It will also likely require breaking changes for public APIs so I think given the amount of change we are asking of developers at the moment (develop for blocks instead of shortcode), I think it's best we keep what we have.

Some discussion has happened in here. Maybe the next step would be to summarize where there appears to be agreement and summarize any changes to the original proposal.

I can do that next week

I think there is a benefit in surfacing this discussion to a larger audience via the blog on developers.woocommerce.com. You can include a summary of the proposal in that (or point to a summary in this discussion).

Yep I agree, as long as we summarise the discussion and present it rather than specifically ask for feedback, because I think that will complicate and delay any decision here.

[alexflorisca]

To summarise what's been said:

• Deprecation window
  • There's convergence around 2 year deprecation window being too big.
  • 1 year would be more suitable to align with last 2 WP releases supported by WC.
  • There may be cases where it's suitable to move much faster, in the cases where the, as Nadir put it for APIs that prove to be over-powered or over-permissive that it risks the level playing field or consistency of a store
  • My suggestion is not commit to a hard limit, but to provide a guideline, and encourage developers to keep an eye on deprecation warnings
• We won't use the \Internal namespace as that's not necessarily private
• Lock/unlock API doesn't work for our use case without significant refactoring. We will stick with prefixing experimental features with __experimental, and adding deprecation notices.
• We will not graduate ALL existing experimental interfaces
• We will review experimental interfaces every 6 months
  • We could schedule this and set up a tracking issue or a discussion for this and provide updates for each review round with what was deprecated, removed, graduated.

Some questions I still have

• How do we enforce this across all the teams in Woo?
• Who will own the review of the experimental features?
• How do we best schedule it so it isn't forgotten?
• Is this something that will be done by the teams in A8C or the wider WC community?

[nerrad]

Deprecation window
...My suggestion is not commit to a hard limit, but to provide a guideline, and encourage developers to keep an eye on deprecation warnings

I agree with not having a hard limit, but I think it'd be useful to have a guideline that describes upper and lower bounds (along with the rationale for choosing either).

We won't use the \Internal namespace as that's not necessarily private

Hmm. This is a bit puzzling to be honest. My understanding is that WooCommerce has explicitly communicated the Internal namespace as subject to change and not intended as a public API? The technical application argument "that's not necessarily private" equally applies to prefixing anything with __experimental.

Lock/unlock API doesn't work for our use case without significant refactoring. We will stick with prefixing experimental features with __experimental, and adding deprecation notices.

I appreciate this signal as a warning to be careful about using these APIs, however, it's still private and I think we will need to make sure if we change the shape of the API that there is a non-breaking compatibility layer that exists for a few versions to handle public usage of the APIs.

We will not graduate ALL existing experimental interfaces

Even if an experimental interface is not graduated, there should be consideration about how something is removed with no replacement. Things like:

• searching for usage in the available data sets to gauge impact.
• communication about removal far in advance of the actual removal. This can include covering where this would be communicated and potential alternatives for solutions built with the API.
• Implementing fallbacks to limit the impact on stores that have code using the API (especially considering the update cycles of various extensions/custom code have varying overlaps with WooCommerce).

Regarding your open questions

How do we enforce this across all the teams in Woo?

I think we can start making this a policy for code in the WooCommerce monorepo and then internally promote this as something teams could adopt for their extensions (agreeing on something for WooCommerce makes it easier to adopt across extensions).

Who will own the review of the experimental features?

Whatever team has implemented the feature (so that could be multiple teams doing reviews of features they added). An automation could be set up on a regular period that creates a GH issue for reviewing experimental features. Ideally, the automation would tag the individual who committed the experimental feature in the list to aid with getting the review.

How do we best schedule it so it isn't forgotten?

A GH action workflow probably would work well for this. Gutenberg does something similar for its releases (see here). I think the content used in the GH issues is generated by this script.

Is this something that will be done by the teams in A8C or the wider WC community?

I don't understand why this is a question, but my first reaction is it doesn't matter at this point.