[docs] Add SCSS deprecation page

general/development/policies/codingstyle/index.md

@@ -2028,7 +2028,7 @@ If you have a big task that is nearly done, apart a few TODOs, and you really wa
 
 There is a nice "to-do checker" reporting tool, restricted to admins and available via web @ [`lib/tests/other/todochecker.php`](https://github.com/moodle/moodle/blob/master/lib/tests/other/todochecker.php).
 
-Finally, don't forget to add any MDL-12345 used by your TODOs (and @todos too, unless part of the [deprecation process](../deprecation.md), those are handled apart) to the "Review TODOs Epic": MDL-47779 (requires login to see the issues)
+Finally, don't forget to add any MDL-12345 used by your TODOs (and @todos too, unless part of the [deprecation process](../deprecation/index.md), those are handled apart) to the "Review TODOs Epic": MDL-47779 (requires login to see the issues)
 
 ### CVS keywords
 

general/development/policies/deprecation/index.md

@@ -232,5 +232,6 @@ Named parameter arguments are available from PHP 8.0 onwards.
 - [String deprecation](../../../projects/api/string-deprecation.md)
 - [External functions deprecation](/docs/apis/subsystems/external/writing-a-service#deprecation)
 - [Capabilities deprecation](/docs/apis/subsystems/access#deprecating-a-capability)
+- [SCSS deprecation](./scss-deprecation.md)
 - [Process](../../process.md)
 - [Release process](../../process/release/index.md)

general/development/policies/deprecation/scss-deprecation.md

@@ -0,0 +1,92 @@
+---
+title: SCSS Deprecation
+tags:
+  - Processes
+  - Core development
+  - Deprecation
+  - SCSS
+---
+
+## When should SCSS be deprecated?
+Since Moodle 4.4, it's possible to deprecate SCSS styles and classes. This allows us to safely remove SCSS and will help us keep the code cleaner and more organized.
+
+The most common scenarios where this functionality can be used is when specific SCSS code is not being used anywhere, when the name of a class is changed or a class should not be used in the future.
+
+:::tip
+
+If all the styles depending on the same parent are deprecated, is strongly recommended to deprecate the parent selector.
+
+:::
+
+## How it works
+
+A new SCSS file called `deprecated.scss` has been added to the `theme/boost/scss/moodle` folder. All the deprecated SCSS code should be added to this file.
+
+In this file a new mixin called `deprecated-styles` has been also added. This mixin will add a red backgound to the deprecated styles and also a `:before` pseudo-element with the text "Deprecated style in use". It is important to note that `deprecated-styles` mixin will only affect sites with `themedesignermode` setting enabled or behat test running sites.
+
+## How to deprecate SCSS code
+
+To deprecate SCSS code, follow these steps:
+
+1. Remove the SCSS code that is no longer in use from the original file.
+2. Add the removed SCSS code to the `deprecated.scss` file.
+3. Add the `deprecated-styles` mixin to the removed SCSS code.
+4. Add a comment to the removed SCSS code explaining why it has been deprecated.
+
+**Example 1: SCSS code is no longer in use**
+
+```scss title="theme/boost/scss/moodle/deprecated.scss"
+// The following styles are deprecated because they are no longer in use.
+// Deprecating the parent selector that contains all the deprecated styles.
+.path-course-view li.activity .foo {
+  @include deprecated-styles();
+}
+.path-course-view li.activity .foo > a {
+  text-decoration: none;
+  color: $secondary;
+}
+.path-course-view li.activity .foo > a:hover {
+  color: $primary;
+}
+```
+
+**Example 2: Helper class has been renamed**
+
+```scss title="theme/boost/scss/moodle/deprecated.scss"
+// The class ".foo" is deprecated. Use ".bar" instead.
+.foo {
+  @include deprecated-styles();
+
+  color: $pink;
+  @include border-right-radius(0);
+  border: $border-width solid $border-color;
+  table {
+    margin: 1rem;
+  }
+  table > tbody {
+    padding: .5rem;
+  }
+}
+```
+
+## Check deprecated styles in Behat tests
+
+Is is possible to check if deprecated styles are being used while running Behat tests. To do so, add the `--scss-deprecations` flag to the Behat init command.
+
+```bash
+php admin/tool/behat/cli/init.php --scss-deprecations
+```
+
+Then, when running Behat tests, the following message will be displayed:
+
+```bash
+Run optional tests:
+...
+- SCSS deprecations: Yes
+```
+
+If deprecated styles are being used, the test will fail with the following message:
+
+```bash
+Deprecated style in use (Exception)
+```

general/development/process.md

@@ -319,7 +319,7 @@ Decisions will be posted on the issue and that issue will be closed, allowing an
 
 - [Detailed workflow](./process/_files/workflow.jpg)
 - [Release process](./process/release)
-- [Deprecation](./policies/deprecation.md)
+- [Deprecation](./policies/deprecation/index.md)
 - [Integration dashboard](http://tracker.moodle.org/secure/Dashboard.jspa?selectPageId=11350)
 Walks-though of the process for contributors:
 - By Dan Poltawski, Integrator: http://www.slideshare.net/poltawski/how-to-guarantee-your-change-is-integrated-to-moodle-core, https://www.youtube.com/watch?v=836WtnM2YpM

general/development/process/peer-review/index.md

@@ -182,7 +182,7 @@ Ensure that:
 
 - The PHPdoc comments on all classes, methods and fields are useful. (Comments that just repeat the function name are not helpful! Add value.)
 - Where an API has been changed significantly, the relevant upgrade.txt file has been updated with information.
-- Where something has been deprecated, that the comments don't just say "do NOT use this any more!!!" but actually follow the [deprecation policy](../../policies/deprecation.md).
+- Where something has been deprecated, that the comments don't just say "do NOT use this any more!!!" but actually follow the [deprecation policy](../../policies/deprecation/index.md).
 - Appropriate [labels](../../tracker/labels.md) have been added when there has been a function change, particularly
   - docs_required (any functional change, usually paired with `ui_change`),
   - dev_docs_required (any change to APIs, usually paired with `api_change`),

general/development/process/release/index.md

@@ -190,4 +190,4 @@ Usually on Monday
 
 ## See also
 
-- [Deprecation process](../../policies/deprecation.md)
+- [Deprecation process](../../policies/deprecation/index.md)