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/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