justinfagnani
commented
1 year ago 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
sorvell
tbroyer
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:
ReactiveElement.createProperty(),.getPropertyDescriptor(), 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.
Current Behavior
Desired Behavior
References