diff --git a/docs/guides/javascript/deprecation.md b/docs/guides/javascript/deprecation.md new file mode 100644 index 000000000..f75069cdf --- /dev/null +++ b/docs/guides/javascript/deprecation.md @@ -0,0 +1,131 @@ +--- +title: Deprecation of JavaScript +tags: + - deprecation +--- + +The deprecation of JavaScript follows the same general principle as the deprecation of other Moodle code. That is: + +- Deprecations should only be on the `main` branch, not on stables. Exceptions to this may be made in certain conditions, including: + - for some external service integrations + - where a feature is discovered to have been broken irreparably + - to address security issues +- Deprecations apply to all public APIs, classes, and files. +- All deprecations should be noted with an [upgrade note](/general/development/upgradenotes). +- Deprecations are split into three stages: + 1. Initial deprecation + 2. Final deprecation + 3. Removal +- All deprecations should emit debugging notices where possible + +## JavaScript specifics {/* #JavaScript-specifics */} + + + +From Moodle 5.2 a new deprecation utility is included in Moodle core for JavaScript. That can be found in the `core/deprecated` AMD module and is intended to function in a similar way to its PHP Attribute equivalent. + +### Usage {/* #usage */} + +The `core/deprecated` module exports a single, default, function which can be used to emit appropriate deprecation information when called. + +This may be included in places such as: + +- the body of the file, not in any method, so that the use of the file emits the deprecation notices; and +- within a method, so that when a method is called the deprecation notice is emitted. + +The basic usage of the API requires that a description of the thing being deprecated is provided. Other arguments are optional, but at least one of the following must be provided: + +- the reason for deprecation; +- the replacement to use; or +- the MDL in which the item was deprecated. + +```javascript title="Basic usage" +import emitDeprecation from 'core/deprecated'; + +export const myFunction = (the, args) => { + emitDeprecation('myFunction', { + replacement: 'myNewFunction', + since: '5.2', + mdl: 'MDL-12345', + }); + + const modified = args.slice(0, 1); + args = args.slice(1); + + // Call myNewFunction. + return myNewFunction(the, modified, args); +} +``` + +When this method is called the following actions will happen: + +- a notice will be printed to the browser console; and +- a modal will be displayed. + +This deprecation will cause failures when running Behat if any code path makes use of the functionality. + +#### Silent deprecation {/* #silent-deprecation */} + +In some cases it is necessary to deprecate a feature silently, emitting to the console but not displaying any modal. This may happen for deprecation of widely used features over a longer period where the initial deprecation is expected to take a long time. + +To do this, you can set the `emit: false` property on the deprecation call: + +```javascript title="Emitting in the Console only" +import emitDeprecation from 'core/deprecated'; + +export const myFunction = (the, args) => { + emitDeprecation('myFunction', { + replacement: 'myNewFunction', + since: '5.2', + mdl: 'MDL-12345', + emit: false, + }); + + const modified = args.slice(0, 1); + args = args.slice(1); + + // Call myNewFunction. + return myNewFunction(the, modified, args); +} +``` + +#### Final deprecation {/* #final-deprecation */} + +After the initial deprecation period, deprecations typically then become 'final'. This means that instead of a warning being issued and a backwards-compatible call being made, an Error is shown. + +In some cases deprecations may also be marked as final because there is no alternative. + +To mark a deprecation as final, you can set the `final: true` property on the deprecation call: + +```javascript title="Basic usage" +import emitDeprecation from 'core/deprecated'; + +export const myFunction = (the, args) => { + emitDeprecation('myFunction', { + replacement: 'myNewFunction', + since: '5.2', + mdl: 'MDL-12345', + final: true, + }); + + const modified = args.slice(0, 1); + args = args.slice(1); + + // Call myNewFunction. + return myNewFunction(the, modified, args); +} +``` + +### Tips and tricks {/* #tips-and-tricks */} + +#### Hiding deprecations {/* #hiding-deprecations */} + +If you wish to stop this deprecation from displaying and from causing Behat failures, you can set the following in your `config.php`: + +```php title="Ignoring the deprecation of 'myFunction'" +$CFG->jsdeprecationignorelist = [ + 'myFunction', +]; +``` + +The name in this list should match the first argument to the `emitDeprecation` method. diff --git a/general/development/policies/deprecation/index.md b/general/development/policies/deprecation/index.md index 0269ec6bd..ddec33e96 100644 --- a/general/development/policies/deprecation/index.md +++ b/general/development/policies/deprecation/index.md @@ -34,13 +34,17 @@ In an open source project, the end use of the codebase varies. People may have c When we talk about Public APIs in Moodle, we are not referring to the `public` keyword in the method definition. -Instead we are considering how that API feature is used. Is that API feature intended to be, or is there a reasonable expectation that it may be, consumed in some reasonable way including: +Instead we are considering how that API feature is used. Is that API feature intended to be, or is there a reasonable expectation that it may be, consumed in some reasonable way including: - being called or accessed externally; or - being overridden in a class OOP sense. ::: +Deprecation applies to all Moodle code, including PHP, JavaScript, templates, React components, web services, and so on. + +The Deprecation policy also applies when code is _changed_ in a way that may break other code. This includes the impact it may have upon areas such as themes, hook subscribers, callbacks, and child templates. + ## Moodle Core deprecation process {/* #moodle-core-deprecation-process */} Once it is decided that a function should be deprecated, a multi-step process should be followed. diff --git a/general/development/policies/deprecation/javascript.md b/general/development/policies/deprecation/javascript.md new file mode 100644 index 000000000..df01e3585 --- /dev/null +++ b/general/development/policies/deprecation/javascript.md @@ -0,0 +1,27 @@ +--- +title: Deprecation of JavaScript +tags: + - deprecation +--- + +The deprecation of JavaScript follows the same general principle as the deprecation of other Moodle code. That is: + +- Deprecations should only be on the `main` branch, not on stables. Exceptions to this may be made in certain conditions, including: + - for some external service integrations + - where a feature is discovered to have been broken irreparably + - to address security issues +- Deprecations apply to all public APIs, classes, and files. +- All deprecations should be noted with an [upgrade note](../../upgradenotes.md). +- Deprecations are split into three stages: + 1. Initial deprecation + 2. Final deprecation + 3. Removal +- All deprecations should emit debugging notices where possible + +## JavaScript specifics {/* #JavaScript-specifics */} + + + +From Moodle 5.2 a new deprecation utility is included in Moodle core for JavaScript. That can be found in the `core/deprecated` AMD module and is intended to function in a similar way to its PHP Attribute equivalent. + +See the [JavaScript Guide to deprecation](/docs/guides/javascript/deprecation) for more information on how to use this feature. diff --git a/general/development/policies/deprecation/templates.md b/general/development/policies/deprecation/templates.md new file mode 100644 index 000000000..0ec45d297 --- /dev/null +++ b/general/development/policies/deprecation/templates.md @@ -0,0 +1,21 @@ +--- +title: Deprecation of templates +tags: + - deprecation +--- + +The Mustache Templating system does not formally support any deprecation process, therefore the deprecation _process_ is slightly different, while the principle and intent is the same. + +For templates and the output component of them, the deprecation policy primarily applies to the context information used to render the template, and passed into child templates. + +The deprecation of Templates follows the same general principle as the deprecation of other Moodle code. That is: + +- Breaking changes to a template have the same impact as a deprecation and should be considered in the same way +- Deprecations should only be on the `main` branch, not on stables. Exceptions to this may be made in certain conditions, including: + - where a feature is discovered to have been broken irreparably + - to address security issues +- All deprecations should be noted with an [upgrade note](../../upgradenotes.md). +- Deprecations are split into three stages: + 1. Initial deprecation + 2. Final deprecation + 3. Removal