RFC: Breaking change policy

[Methuselah96]

Motivation

Perhaps one of the bigger pain-points users have experienced with @types/three are breaking changes, especially when @types/three is a peer dependency of packages like @react-three/fiber and the packages in the surrounding ecosystem.

Proposal

Limit breaking changes to releases that end with a 0 (e.g., 0.160.0, 0.170.0, etc.).

Unresolved questions

three.js itself has a "rolling 10-release breaking change" policy, where they try to maintain backwards compatibility for 10 releases after deprecating a feature.

What should we do if they deprecate a class in r159 and is slated for removal in r169?

1. Remove the class in r160 to keep breaking changes in-line with this new proposal.
2. Remove it in r169. Perhaps the policy would then be: Type-only breaking changes (a change that has no corresponding equivalent change in three.js) follow this new policy, but runtime breaking changes in three.js (which will also be a breaking change for the consumers of the types) continue to make it into any release.

[Methuselah96]

@CodyJasonBennett I'm proposing this mainly as a way to improve the experience for the R3F community and its dependence on @types/three based on your feedback that the types are too volatile. Is this helpful and do you have any thoughts on the question posed at the end?

[CodyJasonBennett]

If I said anything on those lines, it was due to the nature of how three.js versions itself which made hard-coding core features unfeasible in JSX prior.

A more recent example from pmndrs/react-three-fiber#3038 (comment):

You can set skipLibCheck: true in tsconfig.json to bypass this at the moment.

Unfortunately v8 and earlier has to hardcode JSX definitions which is quite error prone since it's impossible to guarantee stability since three.js is in 0.x semver:

https://github.com/pmndrs/react-three-fiber/blob/master/packages/fiber/src/three-types.ts

This is something we changed in the next or v9 branch to be fully dynamic which we're having to thoroughly test against TypeScript inference limitations.

https://github.com/pmndrs/react-three-fiber/blob/v9/packages/fiber/src/three-types.ts

We worked around this in v8 (hardcoded) by adding /** @ts-ignore */ comments so invalid references are ignored, but this is no longer an issue for us in future versions since we've found a proper solution for the dynamicism we need.

Now, we have more regular concerns about features we adopt in JS and consequently TS.

[Methuselah96]

Okay, good to know. I'll shelve this idea for now, and if type-only breaking changes end up becoming more of an issue, reintroduce the idea.