From b328196d329319c7c5d763da1e20a34c3987507c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mikel=20Mart=C3=ADn?= Date: Thu, 16 Nov 2023 15:46:02 +0100 Subject: [PATCH] [docs] Add SCSS deprecation page --- .../development/policies/codingstyle/index.md | 2 +- .../development/policies/deprecation/index.md | 1 + .../policies/deprecation/scss-deprecation.md | 92 +++++++++++++++++++ general/development/process.md | 2 +- .../development/process/peer-review/index.md | 2 +- general/development/process/release/index.md | 2 +- 6 files changed, 97 insertions(+), 4 deletions(-) create mode 100644 general/development/policies/deprecation/scss-deprecation.md diff --git a/general/development/policies/codingstyle/index.md b/general/development/policies/codingstyle/index.md index ba07bd1913..86be630339 100644 --- a/general/development/policies/codingstyle/index.md +++ b/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 diff --git a/general/development/policies/deprecation/index.md b/general/development/policies/deprecation/index.md index 664cbe7320..da08603dd1 100644 --- a/general/development/policies/deprecation/index.md +++ b/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) diff --git a/general/development/policies/deprecation/scss-deprecation.md b/general/development/policies/deprecation/scss-deprecation.md new file mode 100644 index 0000000000..ae4d667245 --- /dev/null +++ b/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) +``` diff --git a/general/development/process.md b/general/development/process.md index f5ecd60c4e..2cfc71e1a2 100644 --- a/general/development/process.md +++ b/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 diff --git a/general/development/process/peer-review/index.md b/general/development/process/peer-review/index.md index 1d1d798f4c..a485e14603 100644 --- a/general/development/process/peer-review/index.md +++ b/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`), diff --git a/general/development/process/release/index.md b/general/development/process/release/index.md index e600d10d8f..c92dde8eb7 100644 --- a/general/development/process/release/index.md +++ b/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)