Create documentation for deprecations and breaking changes and add URLs messages #4776

cartant · 2019-05-12T00:21:07Z

My understanding is that in v6 and v7 there are going to be API deprecations. TSDoc decprecations have been already been added for some of these and they are causing some confusion.

For example, in this issue users of the package gained the mistaken impression that of was deprecated and in this issue, the user was unsure of what was deprecated with startWith(null). In both of these situations, the deprecation messages were due to subtleties with TypeScript's signature matching mechanism.

For contributors, it might be obvious what is and what is not deprecated, but it's understandable that users of the package might be confused by deprecation messages that are reported after a patch upgrade - particular when the deprecation message seems to related to 'normal' use.

We could make this somewhat clearer by creating a simple markdown document for each deprecation that lists what is deprecated and why and could add a link to that document in the deprecation message itself. Doing so should not require too much effort and should go some way to curtailing the opening of deprecation-related issues.

@benlesh @jwo719

The text was updated successfully, but these errors were encountered:

cartant · 2019-05-12T02:53:41Z

See also this issue regarding endWith. That user was passing undefined and without strictNullChecks enabled, undefined will match the signature with the Scheduler in it.

niklas-wortmann · 2019-05-12T05:57:18Z

I like the idea. If all agree to this approach I can prepare the docs site for this!

manojvignesh · 2019-05-28T05:36:39Z

I had the same problem with startWith and didn't understand the documentation which was
deprecated startWith( scheduler: SchedulerLike): MonoTypeOperatorFunction<T> use scheduled and concatAll (e.g. scheduled([[a, b, c], source], scheduler).pipe(concatAll()))
Ended up here to figure out that it's because of the type not getting inferred. Added type like this to solve it startWith(permission.control.value as boolean).

cartant · 2019-06-12T23:56:43Z

I think the deprecation messages themselves need to be improved. Things like this keep popping up because the messages aren't sufficiently specific: https://stackoverflow.com/questions/56571406/is-the-startwith-operator-in-rxjs-really-deprecated

Also, messages should make sense when presented by a linter - not just when reading the TSDoc. For example, outside of the context of the TSDoc, this might not make much sense:

@deprecated In favor of iif creation function: import { iif } from 'rxjs';

Actually, those messages aren't too bad. TSLint reports them like this:

WARNING: .../source/...ts:29:23 - if is deprecated: In favor of iif creation function: import { iif } from 'rxjs';

cartant · 2019-07-23T00:23:55Z

Yet another: #4918

BioPhoton · 2019-08-19T20:27:13Z

Hi @cartant !

From what I understand there are the following problems:

Creating a markdown document for deprecations and lists deprecations plus an explanation.
Add a link to that markdown document in deprecation messages.
Find ways to improve the format of depreciation linter messages.
Find ways to include a link to the deprecations document in the changelog Update changelog to include deprecations #4577

For 1 I believe this is related to #4841 with precondition of #4688

For 2 We can create a script for that. I guess @jwo719 can give details.

For 3 we could use formatter:

current styling

following quick options:

using built-in formatters like stylish

tslint --project tsconfig.json --config tslint.json -t stylish ./index.ts

or we can use custom formatters and extend stylish with links to the docs

tslint --project tsconfig.json --config tslint.json -s ./formatters -t stylishRxJS ./index.ts

POC can be found here

For 4 we could just add another script to the `tools` folder that checks if there are deprecations. If yes ad the link.

Please let me know your opinion

cartant · 2019-08-19T21:20:31Z

Unfortunately, I don't think we should use a formatter.

I was not anticipating a solution requiring developers having to adjust their linting configuration and I don't think we can require them to do that.

IMO, it should report understandable messages - that include a URL - without configuration changes.

I would prefer to see a message like this:

ERROR: 3:11  deprecation  of is deprecated: passing a scheduler to of is deprecated - see https://rxjs.dev/<whatever>

where passing a scheduler to of is deprecated - see https://rxjs.dev/<whatever> is what would be in the TSDoc.

The of is deprecated part of the message is unavoidable - and unfortunate - so I think the message that follows after that is critical. It has to be succinct and understandable and, IMO, followed by a URL that links to a document with a detailed explanation of the reason for - and the implications of - the deprecation.

BioPhoton · 2019-10-03T14:33:14Z

I had a look at your answer and a discussion with @jwo719 about the docs part.

I would do the following things:

Create a list of all deprecations to track the progress
I will remove api/deprecations
In the docs guide section under to menu entry V6 I will create a new page named Deprecations
The content has the following structure:
- Headline follows the pattern: Deprecations introduced prior to <Version_Number> <Date>
  - Deprecation Item
    - Deprecation name
    - Reason for depreciation (whith is the token in the message from the sourcecode
    - Implications of deprecation
    - Refactoring suggestion or link to migrate scripts
    - Link to related remove section
- Headline follows the pattern: "Breaking-changes introduced prior to <Version_Number> "
  - Breaking Change Item
    - Name
    - Link to related deprecation
The content fields should be in JSON format fitting the following structure:

[
  {
    type: 'deprecation' | 'breaking_change'
    name: string,
    version: string,
    date: Date,
    implications?: string,
    refactoring?: string,
    link?: string (link to deprecation or breaking_change depending on type)
  }
]

The created list gets checked by the team
I use the create list and update manually every deprecation message.
The message has the following sections:
- GenericDeprecationError (not customizable)
- HumanReadebleShortMessage ( field `` )
- LinkToDeprecationPage ( url as string )
And follows the pattern:
<GenericDeprecationError> <HumanReadebleShortMessage> - see <LinkToDeprecationPage>

Where <HumanReadebleShortMessage> is the section "Reason for depreciation" in the docs/

BioPhoton · 2019-10-10T13:31:26Z

Here the first draft of the list:

deprecated in 6.0.0-beta.4 (2018-03-29)

deprecated in 6.0.0-rc.0 (2018-03-31)

deprecated in 6.0.0-tactical-rc.1 (2018-04-07)

Scheduler - class - implement own scheduler instead

deprecated in 6.1.0 (2018-05-03)

deprecated in 6.2.0 (2018-05-22)

race - operator function - deprecated

deprecated in 6.4.0 (2019-01-30)

deprecated in 6.5.0 (2019-04-23)

deprecated in 6.5.1 (2019-04-23)

NotificationKind - string litterals instead of enums

deprecated in 7.0.0-alpha.0 (2019-09-18)

deprecated in v7.x

generate - static method - resultSelector needs deprecation. !!!currently missing!!!

removed in v7.x

rxjs-compat removed here

removed in v8.x

BioPhoton · 2019-10-10T13:33:11Z

@cartant
I would need a bit of input about the grouping and reverencing them.

I would like to create a timeline that lists all deprecation by release.
If a deprecation gets removed I list the removal and a link to the deprecation with detailed instructions.

What is the best way to discover in which release the deprecation was introduced?

BioPhoton · 2019-10-10T19:36:42Z

I went through all deprecations and found the version of the introduction.

@benlesh
Please introduce a rule that commits need to mention deprecations!
It took me forever to set up this list. Also, it will take users forever to find out what to do because even in the changelog there is nothing.

Introducing some rules to commit messages and the changelog will help everyone A LOT!

Furthermore, I suggest group similar deprecations within one release. This makes it easier in upgrading versions.

BioPhoton · 2019-10-10T22:35:22Z

I created a first draft of the deprecation page. I would need some feedback about the content and the linking. Sometimes it is pretty repetitive content, especially in the remove sections.

Also the namings: Removed, Old usage, New usage etc are not really good.

I'm happy for every input. :)

In the following my first try:

...

Deprecations introduced prior to 2018-03-29 (6.0.0-beta.4 )

Static method `never` deprecated in favor of constant `NEVER`

`never`	Breaking-Change in version 7.x
Reason	Deprecated because it is more efficient? Some more text here... Some more text here... Some more text here...
Implications	Replacing `never` with `NEVER`

Usage <= 6.0.0-beta.3

import { never } from 'rxjs';

never();

Usage >= 6.0.0-beta.4

import { NEVER } from 'rxjs';
NEVER;

Static method `empty` deprecated in favor of constant `EMPTY`

`empty`	Breaking-Change in version 7.x
Reason	Deprecated because it is more efficient? Some more text here... Some more text here... Some more text here...
Implications	Replacing `empty` with `EMPTY`

Usage >= 6.0.0-beta.3

import { empty } from 'rxjs';
empty();

Usage >= 6.0.0-beta.4

import { EMPTY } from 'rxjs';
EMPTY;

...

Breaking-changes introduced prior to 2018-03-29 (6.0.0-beta.5)

...

Breaking-changes introduced prior to [unknown] (7.x)

Static method `never` removed

Deprecated in version 6.0.0.beta-4 see refactoring suggestions there

Static method `empty` removed

Deprecated in version 6.0.0.beta-4 see refactoring suggestions there

...

cartant · 2019-10-12T00:32:34Z

I like it. I think it will resolve a lot of confusion. If figuring out when the deprecations were added it too tedious, I'd suggest a section titled "Deprecations introduced prior to /* some date */".

BioPhoton · 2019-10-12T00:46:26Z

I updated the draft above and used tables.

Thanks for your feedback and time! <3

I guess I have everything from the content side to start. I will discuss the rest with @jwo719 regarding the integration.

If more feedback pops up, just shoot!

BioPhoton · 2019-10-21T12:04:43Z

@jwo719 I updated the todos with a JSON structure.
Please confirm it so I can start working on it.

niklas-wortmann · 2019-10-21T14:11:13Z

The json structure looks good to me, I could imagine that this could be autogenerated at some point of time!

BioPhoton · 2019-10-21T14:12:31Z

Exactly this is the reason I want to start with a JSON right away. :)

THX for the answer!

cartant added the docs Issues and PRs related to documentation label May 12, 2019

cartant mentioned this issue May 12, 2019

fix(endWith): wrap args - they are not observables - in of before concatenating #4735

Merged

cartant self-assigned this Jul 23, 2019

cartant mentioned this issue Aug 12, 2019

Update changelog to include deprecations #4577

Closed

5 tasks

cartant changed the title ~~Add doc URLs to deprecation messages~~ Create documentation for deprecations and breaking changes and add URLs messages Oct 22, 2019

BioPhoton mentioned this issue Nov 7, 2019

4776 add doc ur ls to deprecation messages #5128

Closed

cartant mentioned this issue Apr 24, 2020

Non-type-related issues for v7 beta #5372

Closed

13 tasks

BioPhoton mentioned this issue Jul 30, 2020

How to creating and maintaining custom deprecation information and its related deprecations? push-based/deprecation-manager#23

Closed

6 tasks

This was referenced Oct 5, 2020

[WIP] Roadmap V7 #5795

Closed

Deprecation notes #5821

Merged

samal-rasmussen mentioned this issue Nov 6, 2020

Provide a V7 migration script (e.g. rxjs-6-to-7-migrate) #5843

Closed

2 tasks

cartant closed this as completed in #5821 Mar 13, 2021

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Create documentation for deprecations and breaking changes and add URLs messages #4776

Create documentation for deprecations and breaking changes and add URLs messages #4776

cartant commented May 12, 2019 •

edited

cartant commented May 12, 2019 •

edited

niklas-wortmann commented May 12, 2019 •

edited

manojvignesh commented May 28, 2019

cartant commented Jun 12, 2019 •

edited

cartant commented Jul 23, 2019

BioPhoton commented Aug 19, 2019

cartant commented Aug 19, 2019 •

edited

BioPhoton commented Oct 3, 2019 •

edited

BioPhoton commented Oct 10, 2019 •

edited

BioPhoton commented Oct 10, 2019

BioPhoton commented Oct 10, 2019 •

edited

BioPhoton commented Oct 10, 2019 •

edited

cartant commented Oct 12, 2019

BioPhoton commented Oct 12, 2019

BioPhoton commented Oct 21, 2019

niklas-wortmann commented Oct 21, 2019

BioPhoton commented Oct 21, 2019

Create documentation for deprecations and breaking changes and add URLs messages #4776

Create documentation for deprecations and breaking changes and add URLs messages #4776

Comments

cartant commented May 12, 2019 • edited

cartant commented May 12, 2019 • edited

niklas-wortmann commented May 12, 2019 • edited

manojvignesh commented May 28, 2019

cartant commented Jun 12, 2019 • edited

cartant commented Jul 23, 2019

BioPhoton commented Aug 19, 2019

For 1 I believe this is related to #4841 with precondition of #4688

For 2 We can create a script for that. I guess @jwo719 can give details.

For 3 we could use formatter:

For 4 we could just add another script to the tools folder that checks if there are deprecations. If yes ad the link.

cartant commented Aug 19, 2019 • edited

BioPhoton commented Oct 3, 2019 • edited

BioPhoton commented Oct 10, 2019 • edited

BioPhoton commented Oct 10, 2019

BioPhoton commented Oct 10, 2019 • edited

BioPhoton commented Oct 10, 2019 • edited

...

Deprecations introduced prior to 2018-03-29 (6.0.0-beta.4 )

Static method never deprecated in favor of constant NEVER

Static method empty deprecated in favor of constant EMPTY

...

Breaking-changes introduced prior to 2018-03-29 (6.0.0-beta.5)

...

...

Breaking-changes introduced prior to [unknown] (7.x)

Static method never removed

Static method empty removed

...

...

cartant commented Oct 12, 2019

BioPhoton commented Oct 12, 2019

BioPhoton commented Oct 21, 2019

niklas-wortmann commented Oct 21, 2019

BioPhoton commented Oct 21, 2019

cartant commented May 12, 2019 •

edited

cartant commented May 12, 2019 •

edited

niklas-wortmann commented May 12, 2019 •

edited

cartant commented Jun 12, 2019 •

edited

For 4 we could just add another script to the `tools` folder that checks if there are deprecations. If yes ad the link.

cartant commented Aug 19, 2019 •

edited

BioPhoton commented Oct 3, 2019 •

edited

BioPhoton commented Oct 10, 2019 •

edited

BioPhoton commented Oct 10, 2019 •

edited

BioPhoton commented Oct 10, 2019 •

edited

Static method `never` deprecated in favor of constant `NEVER`

Static method `empty` deprecated in favor of constant `EMPTY`

Static method `never` removed

Static method `empty` removed