docs/contribution/deprecated-features.md
If you feel a "public" feature(API) is not needed anymore, mark it as deprecated before you can completely remove it from the engine.
Don't take anything for granted: do not suppose that the features should not have been used by users. The publics is public once it was public. The publics for example are module exports, public class members, fields of public interfaces.
You should take the following rules to mark a feature as deprecated.
Mark the API as deprecated using JsDoc:
/**
* @deprecated Reason or detail.
*/
export function f () {}
Illustrate the version you deprecate it. An explanation couldn't be better.
When building the engine, users may be allowed to remove a version range of deprecated features. Below is the common practice.
Put a serials of deprecated features, with same deprecating date, in a module file with stem name as deprecated-${version}, the version is the version since where you deprecate them. version shall be a valid semver version. For example 1.2.0 instead of 1.2. If the version is in the specific range, the module will be removed.
You may also simplify the stem name as deprecated.
In such cases, the module is removed regardless of the user specified range. But it's strongly not recommended.
Such a name convention is applied to all module files of engine.
The regular module file names should not starts with a deprecated or deprecated- prefix.
The "removal" is implemented as if each of the module is replaced as an empty module: export {};. Due to this,
you shall not do named import/export from deprecated modules
in modules that would be included in the building. For example, the following is not permitted:
export { Deprecated } from './deprecated-1.2.0';
In most cases, the named import/export is not required. If it does, simply constructs an also-deprecated module and export it:
// Module select-deprecated-1.2.0
export { Deprecated } from './deprecated-1.2.0';
and the importing module:
export * from './select-deprecated-1.2.0';