Request For Comment: Deprecation Process

[aciccarello]

Problem

There have been a couple instances of features which were implemented but are no longer our recommended approach (#1029 and now #1080). So far we have sought to maintain support while encouraging the preferred pattern. However, that still leaves us supporting the old pattern.

I would like to suggest that we have a process for how features are deprecated.

Suggested Solution

I suggest a multi-step approach

1. Implement preferred feature
   • Document on typedoc.org preferred approach and note discouraged pattern
2. In a later release start logging warnings of deprecated pattern
   • Note change in changelog as breaking change to encourage users to switch to new feature
3. In a later release completely remove deprecated feature

Please let me know what you think of this plan. Concerns and alternate suggestions welcome.

[Gerrit0]

This seems reasonable to me, but we should probably define a timeline (or # of releases) for each of the steps. My main concern is that we need to make deprecated patterns and their replacements very easy to find. For a documentation tool, we still have pretty poor docs despite the recent work.

More things to consider

• What is our public API? Almost every plugin imports stuff from typedoc/dist/... which seems like accessing internals. Unfortunately, there is no better way to do it right now. Create a "How to write a typedoc plugin" for boosting community plugins #521
• Plugins can either specify a load function or export = a function support ES6/ES2015-style import syntax for plugins #594
• Specifying options - typedocOptions key in tsconfig.json vs typedoc.json vs typedoc.js

[Gerrit0]

I've started leaving comments in the code when I come across something that wants deprecating, they usually go something like this:

// discourage 0.13, warn 0.17, remove 0.19

To mark when a given feature began to be discouraged, when we should start giving warnings (I'm not planning any warnings before 0.17), and when it should be removed. Generally I don't want to start warning on a given feature until at least one minor version has passed, and it shouldn't be removed until at least one minor version after that, though for more common options I've been leaving larger gaps.

In particular, the src property can be used in typedoc.json to specify the input files. In 0.16 the inputFiles option will be available to replace it, so in 0.17 I'll add a warning while still preserving the previous behavior. Then in 0.19 the logic to convert src to inputFiles will be removed along with the warning.

This is in contrast to support for autodiscovery of typedoc.js, which is an incredibly popular feature (>40% of the configuration files I've looked at for TypeDoc use JS instead of JSON config files!). I don't really want to deprecate/remove that until we have a properly stable API... but I will be updating docs to encourage the use of JSON files.