[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,120 @@
+---
+title: SCSS Deprecation
+tags:
+  - Processes
+  - Core development
+  - Deprecation
+  - SCSS
+---
+import { Since } from '@site/src/components';
+
+<Since versions={["4.4"]} issueNumber={"MDL-78334"} />
+
+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.
+
+:::info When should SCSS be removed?
+
+There are situations where deprecation does not make sense. For example when a whole functionality is being removed, or a very specific SCSS class is no longer used by the code. If it is very unlikely that the SCSS class is used by any other code, it can simply be removed without the full deprecation process.
+
+:::
+
+## 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.
+
+:::tip
+
+If all the styles depending on the same parent are deprecated, is strongly recommended to deprecate the parent selector.
+
+:::
+
+## 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 under the comment for the current version `// Deprecated since Moodle X.Y.`
+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.
+
+:::note
+
+If there is no section for the current version in the `deprecated.scss` file, it should be added. See [Final deprecation](#final-deprecation).
+
+:::
+
+**Example 2: Helper class has been removed**
+
+```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;
+  }
+}
+```
+
+**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;
+}
+```
+
+## Final deprecation
+
+When adding SCSS code to the `deprecated.scss` file, it is important to add it under the comment with the version when the code was deprecated. If that comment still doesn't exist, it should be added:
+
+```scss title="theme/boost/scss/moodle/deprecated.scss"
+//
+// Deprecated since Moodle X.Y.
+//
+```
+
+And alongside with that, a new issue should be created in the tracker to remove the deprecated SCSS code with the title `Remove strings deprecated in X.Y` and in the epic `X.[Y+4]` deprecations.
+
+After 4 major versions, the deprecated SCSS code will be removed from the `deprecated.scss` file.
+
+## 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)