The information about a certain deprecation in the library also includes the version when the breaking change will happen as well as code examples for the usage before and after the deprecation.
This snippets are presented as highlited text in the migration timeline and also open up the code in StackBlitz. To provide maintainable code examples we can use version range specifier to let StackBlitz automatically install new versions until the version of the breaking change.
To implemet this we need 2 information:
- the version where the deprecation was introduced
- the version where the breaking change will happen
The version of deprecation is very easy to get. We have it when introducing the new deprecation to our data set.
A example for a version number could lok like this:
6.0.0-alpha46.2.07.0.1
To get the information for the version of breaking change I thought about it in the following way:
Based on the assumption that RxJS is following semantic versioning the breaking change for a introduced deprecation happens with a major version change. So if a deprecation is introduzed in version 6.0.0-alpha4 it can only break in version
7.0.0-alpha.0to7.0.0,8.0.0-alpha.0to8.0.0,9.0.0-alpha.0to9.0.0, etc...
The next assumption is based on the high usage of the library. As so many people use it, the team has to move slow with changes/deprecations and do it strategically.
This made me beleife that the person that introduces a deprecation has to have a detailed knowledge of when the deprecation should break.
So the person introduces a deprecation in version 6.0.0-alpha4 already knows that it will break in version 8.x, but not the specific version.
So the version of breaking change is a more like a range, i.e. 7.0.0 and higher:
Examples could be:
678
So if display the information for a breaking change in the deprecation timeline
we place the item in the first existing release with major version 8.
This assumptions are used to:
- autogenerate and prefill missing breaking change items to save maintainance work
- link to the breaking change item in the time line
- provide auto-maintained code examples for before and after snippets.
We use tooling to autogenerate a first version of the breaking change items.
If the breaking version is 8 we and no release within version 8 exists we create a release for version 8.0.0 and insert it there.
As code examples are part of every deprecation item and also can be opened in StackBlitz we have to provide a different version of RxJS in the package.json dependencies for each code example.
This is solved over version ranges as it takes away a lot of maintainance.
Example: For a deprecation
- introduced in version 6.0.0-alpha4
- brekaing in version 8.0.0
the following version specifier are set for the rxjs dependencie in StackBlitz:
- before deprecation: <6.0.0-alpha4
- after deprecation: >=6.0.0-alpha4 <8.0.0
Example of a deprecation item:
