From 9b050433287e2a550d74f7649c05d1f8dd458b66 Mon Sep 17 00:00:00 2001 From: Sara Arjona Date: Mon, 12 Aug 2024 11:03:11 +0200 Subject: [PATCH] [general] Add Icon deprecation policy --- docs/devupdate.md | 8 ++ .../policies/deprecation/icon-deprecation.md | 110 ++++++++++++++++++ .../development/policies/deprecation/index.md | 1 + .../policies/deprecation/scss-deprecation.md | 2 +- 4 files changed, 120 insertions(+), 1 deletion(-) create mode 100644 general/development/policies/deprecation/icon-deprecation.md diff --git a/docs/devupdate.md b/docs/devupdate.md index ff082e0b18..91cd31cbb7 100644 --- a/docs/devupdate.md +++ b/docs/devupdate.md @@ -94,6 +94,14 @@ Check changes in any of the core plugins that implement the reset course method. ::: +## Deprecations + +### Icon deprecation + + + +A new mechanism for deprecating icons has been introduced. More information can be found in the [icon deprecation documentation](/general/development/policies/deprecation/icon-deprecation). + ## Filter Plugins diff --git a/general/development/policies/deprecation/icon-deprecation.md b/general/development/policies/deprecation/icon-deprecation.md new file mode 100644 index 0000000000..2db331ffb2 --- /dev/null +++ b/general/development/policies/deprecation/icon-deprecation.md @@ -0,0 +1,110 @@ +--- +title: Icon deprecation +tags: + - Processes + - Core development + - Deprecation + - Icon +--- + + + +Since Moodle 4.5, it's possible to safely deprecate and remove icons. + +:::info When should icons be removed? + +There are situations where deprecation does not make sense. For example when a whole functionality is being removed, or a very specific icon is no longer used by the code. If it is very unlikely that the icon is used by any other code, it can simply be removed without the full deprecation process. + +::: + +## How it works + +A new method, `get_deprecated_icons()`, has been added to the `icon_system` class. All deprecated icons should be registered through this method. +Plugins can implement a callback to `pluginname_get_deprecated_icons()` to register their deprecated icons too. + +## How to deprecate an icon + +To deprecate an icon, follow these steps: + +1. Add the deprecated icon to the proper `get_deprecated_icons()` method (`lib/classes/output/icon_system_fontawesome.php` for core icons and `pluginname_get_deprecated_icons()` for plugins), under the comment for the current version `// Deprecated since Moodle X.Y.` +2. Add a comment to the removed icon explaining why it has been deprecated. + +:::note + +If there is no section for the current version in the `get_deprecated_icons()` method, it should be added. See [Final deprecation](#final-deprecation). + +::: + +**Example 1: Deprecate core icon** + +```php title="lib/classes/output/icon_system_fontawesome.php" + #[\Override] + public function get_deprecated_icons(): array { + // Add deprecated core icons to parent deprecated icons. + return array_merge( + parent::get_deprecated_icons(), + [ + // + // Deprecated since Moodle 4.5. + // + 'core:a/em1_bwgreater', + ], + ); + } +``` + +**Example 2: Deprecate plugin icon** + +```php title="pluginname_get_deprecated_icons() callback" + /** + * Get the list of deprecated icons. + * + * @return array with the deprecated key icons. + */ + function mod_forum_get_deprecated_icons(): array { + return [ + // + // Deprecated since Moodle 4.5. + // + 'mod_forum:t/unsubscribed', + ]; + } +``` + +## Final deprecation + +When adding icons to the `get_deprecated_icons()` method, 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: + +```php title="Add a comment in the get_deprecated_icons() method" + [ + // + // Deprecated since Moodle 4.5. + // + ]; +``` + +And alongside with that, a new issue should be created in the tracker to remove the deprecated SCSS code with the title `Remove icons deprecated in X.Y` and in the epic `X.[Y+4]` deprecations. + +After 4 major versions, the deprecated icons will be removed from the `get_deprecated_icons()` methods. + +## Check deprecated icons in Behat tests + +Behat tests are now checking for deprecated icons. When running Behat tests, the following message will be displayed: + +```bash +Run optional tests: +[...] +- Icon deprecations: Yes +``` + +If deprecated icons are being used, the test will fail with the following message: + +```bash +Deprecated icon in use. Enable $CFG->debugdisplay for detailed debugging information in the console (Exception) +``` + +This check can be disabled by using the `--no-icon-deprecations option` flag in the behat CLI. + +```bash +php admin/tool/behat/cli/init.php --no-icon-deprecations +``` diff --git a/general/development/policies/deprecation/index.md b/general/development/policies/deprecation/index.md index 22dfde790b..e166af10af 100644 --- a/general/development/policies/deprecation/index.md +++ b/general/development/policies/deprecation/index.md @@ -275,6 +275,7 @@ Named parameter arguments are available from PHP 8.0 onwards. - [Deprecation attributes](/docs/apis/core/deprecation/) - [External functions deprecation](/docs/apis/subsystems/external/writing-a-service#deprecation) - [Capabilities deprecation](/docs/apis/subsystems/access#deprecating-a-capability) +- [Icon deprecation](./icon-deprecation.md) - [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 index a90ac1c3b7..51299075cf 100644 --- a/general/development/policies/deprecation/scss-deprecation.md +++ b/general/development/policies/deprecation/scss-deprecation.md @@ -1,5 +1,5 @@ --- -title: SCSS Deprecation +title: SCSS deprecation tags: - Processes - Core development