rxjs: Create documentation for deprecations and breaking changes and add URLs messages

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

…

…

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/

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