Create documentation for deprecations and breaking changes and add URLs messages

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

[BioPhoton]

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

…

…

[BioPhoton]

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 <HumanReadebleShortMessage> 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> <Date>”
    • 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/