[RRFC] Breaking change policy and tracking post-3.0 breaking changes

[justinfagnani]

• I searched for an existing RRFC which might be relevant to my RRFC

Motivation

We should develop a breaking change policy so our users know what to expect in future releases and how we approach stability and backwards compatibility. This can include hard policies like deprecating an API in a release before removing it, or softer policies like trying to not make breaking changes unless we need to, improves our code quality, performance, maintenance burden, etc.

We should also try to develop some more precise browser-support policies for relying on new features, possibly based on usage and whether there's a polyfill. For example, we could not rely on a new non-polyfillable feature if > X% of browser usage doesn't support the feature, and not rely on a polyfillable feature of > Y% of browser usage doesn't support the feature.

And not a request for a specific RFC per se, but I'd like for us to keep track of potential breaking changes that we might want to make in order to help with longer term planning and carefully minimize disruptions to developers and users.

Example

Examples of breaking changes would could make that could improve our source and published code:

• Using and publishing private fields (ES2022)
• Relying on Constructible StyleSheets (Supported in Chrome 73, FF 101, Safari 16.4)
• Removing support for TypeScript experimental decorators
• Not reflecting initial property values to attributes
• Removing ReactiveElement.createProperty(), .getPropertyDescriptor(), etc.
• Using the DOM Parts API when it lands.
• etc

How

For the breaking change policy, the RFC itself can serve as documentation of it. We may find a good place in the lit.dev docs as well.

For tracking ideas, we can use several methods, though it's important to remember that all breaking changes will need to be part of an RFC to get approval for actually making it.

1. Mention the idea in this issue
2. Propose a standalone RFC
3. Include the breaking change as part of a larger RFC
4. File an issue in lit/lit

Current Behavior

Desired Behavior

References

• n/a

[justinfagnani]

It'd be nice to enumerate some principles and axioms we have around breaking changes in the RFC. Things like:

• No breaking changes is best. We strive to keep things as stable as possible.
• Fewer and smaller breaking changes per major version are better than more and bigger breaking changes. We should make majors as easy to upgrade to as possible. If breaking changes are small enough and scoped enough, then not everyone will be affected by the change.
• Given that, more frequent breaking changes are often better than less frequent large breaking changes. Incrementally upgrading through a series of majors is more feasible since you have stable waypoints.
• Expected reasons we might break things: While we strive to keep our APIs and behavior stable, we don't want to be completely locked into current behavior and browser support. We don't have infinite capacity to carry along workarounds indefinitely, test on all versions of browsers, etc. Users and developers also benefit when we can reduce code size by using newer browser and JS APIs or newer JS language features. We want to balance stability with nimbleness.
• Existing code using an existing version of Lit will not spontaneously break. This may seem like a given, but not everyone realizes this and sometimes get afraid that a major version will break their site. This could be because of experience with frameworks?
• Versions help with upgrading, but are not a panacea. Since we are not a framework, each component can use the version of Lit that it needs. This is great! On the other hand, we don't want bundle bloat from many version of Lit being required for a page.
• Major versions shouldn't really have new features, unless those features somehow require a change in behavior. New features should be backwards compatible and come in minor versions. This is sometimes in tension with marketing.
• We should deprecate features before removing them. Ideally we deprecate in a major version and release in the next. At the very least, in extenuating circumstances, we deprecate in the last minor before a major version. That way developers can upgrade to the new minor, resolve deprecation warnings, then upgrade to the major.
• We should strive to include code mods to automatically upgrade developers to new APIs when applicable.

[filimon-danopoulos-stratsys]

Would it be reasonable to also include a commitment in regards to supported older versions? A bad example maybe but say that I still need IE11 support. It would be nice to know that, by policy, bugfixes from 3.X still be backported to 2.X (or not). The documentation also needs somethings similar, will the 2.X docs be accessible after 3.X is released?

It's reasonable to not maintain 2.X indefinitely and it would be nice to have a roadmap of when an older version is considered unsupported. This would help in planning potential upgrades.

[justinfagnani]

Part of the RRFC is asking for a more formal breaking change and supported browser policy.

We'll need to discuss it, but I think we are unlikely to backport most changes, especially if we keep the number and severity of breaks to a minimum. The cost is probably to high for us, so I bet the recommendation will be to upgrade. We will need to discuss that, of course.

If we here of specific cases of difficulty upgrading plus a need for a critical bug fix, we may make one-off decisions to backport, or to accept PRs that do.

[sorvell]

I think supporting the last 2 versions of each major browser is a good baseline that allows a reasonable pace of advancement without too much churn. While Chrome/Firefox release fast and users upgrade fast, Safari releases slowly so this effectively equates to a roughly 1-2 year cycle in significant changes.

Back-porting critical fixes (only) to versions supporting older browsers seems reasonable.

[tbroyer]

How about Firefox ESR? https://support.mozilla.org/en-US/kb/firefox-esr-release-cycle / https://whattrainisitnow.com/calendar/

How about Samsung Internet? (based on Chromium but apparently pulls from upstream at a much slower pace than Chromium's release cadence)

[justinfagnani]

FYI, we already test on Firefox ESR