From 94ab47252a23b92eab92bde73eee2ba6588b2193 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 | 120 ++++++++++++++++++ general/development/process.md | 2 +- .../development/process/peer-review/index.md | 2 +- general/development/process/release/index.md | 2 +- 6 files changed, 125 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..b38837b26b --- /dev/null +++ b/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 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) +``` 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 2a0034e8cb..4e8ecff2ad 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)