Document template documentation

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 */}
+
+<Since version="5.2" issueNumber="MDL-87867" />
+
+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.

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.

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 */}
+
+<Since version="5.2" issueNumber="MDL-87867" />
+
+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.

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