Skip to content

Commit e41613e

Browse files
snakesnake
committed
[docs] document plugin/subplugin type deprecation
1 parent c9f7f90 commit e41613e

File tree

4 files changed

+252
-0
lines changed

4 files changed

+252
-0
lines changed

‎docs/apis/plugintypes/index.md

+140
Original file line numberDiff line numberDiff line change
@@ -132,6 +132,146 @@ foreach ($pluginman->get_plugin_types() as $type => $dir) {
132132

133133
</details>
134134

135+
## Plugin type deprecation
136+
137+
<Since version="5.0" issueNumber="MDL-79843" />
138+
139+
When a plugin or subplugin type is no longer needed or is replaced by another plugin type, it should be deprecated.
140+
Using `components.json` or `subplugins.json` plugin types and subplugin types, respectively, can be marked as deprecated.
141+
142+
The process for plugin/subplugin type deprecation differs slightly to normal [Deprecation](/general/development/policies/deprecation) process.
143+
Unlike with code deprecation, where the deprecated class or method is usually expected to remain functional during the deprecation window, deprecated plugin/subplugin types are treated as end-of-life as soon as they are deprecated.
144+
145+
Once deprecated, core will exclude plugins of the respective plugin type when performing common core-plugin communication, such as with hooks, callbacks, events, etc.
146+
In the case of subplugins, the expectation is that the component code (the component under which the subplugins reside), will have been updated and all references to the subplugins removed/replaced, before the time of deprecation.
147+
148+
Class autoloading and string resolution is still supported during the deprecation window, to assist with any plugin migration scripts that may be required.
149+
150+
:::info limitations
151+
Whilst both plugin and subplugin types can be deprecated, only those plugin types _not_ supporting subplugins can be deprecated presently.
152+
:::
153+
154+
### Deprecation process
155+
156+
Deprecation follows a 3 stage process:
157+
158+
1. The plugin/subplugin type is marked as deprecated (a core version bump is also required).
159+
2. The plugin/subplugin type is marked as deleted (a core version bump is also required).
160+
3. Final removal of the plugin/subplugin type from the respective config file.
161+
162+
During first stage deprecation, plugins of the respective type may remain installed, but are deemed end-of-life. This stage gives admins time to remove the affected plugins from the site, or migrate them to their replacement plugins.
163+
164+
In second stage deprecation (deletion), if any affected plugins are still present (i.e. have not been uninstalled/migrated yet) site upgrade will be blocked. These plugins must be removed before continuing with site upgrade.
165+
166+
In final stage deprecation (final removal), the relevant config changes supporting first and second stage deprecation can be removed from the respective config files. This removes the last reference to these plugin/subplugin types.
167+
168+
### Deprecating a plugin type
169+
170+
To mark a plugin type as deprecated or deleted, edit `lib/components.json`, remove the plugin type from the `plugintypes` object and add it to `deprecatedplugintypes`. To mark a plugin type for stage 2 deprecation (deletion), edit the same file and move the plugin type from the `deprecatedplugintypes` object to the `deletedplugintypes` object.
171+
172+
:::info Remember
173+
Don't forget to increment the core version number when marking a plugin/subplugin type for either deprecation or deletion. A version bump isn't needed for final removal.
174+
:::
175+
176+
:::tip Example of plugin type deprecation config values
177+
178+
To mark a plugin type as deprecated in `components.json`, the plugin type should be removed from the `plugintypes` object, and added to a new `deprecatedplugintypes` object.
179+
180+
```json title="lib/components.json demonstrating first stage deprecation of a plugin type"
181+
{
182+
"plugintypes": {
183+
...
184+
},
185+
"subsystems": {
186+
...
187+
},
188+
"deprecatedplugintypes": {
189+
"aiplacement": "ai/placement"
190+
}
191+
}
192+
```
193+
194+
To mark a plugin type as deleted in `components.json`, the plugin type should be removed from the `deprecatedplugintypes` object, and added to a new `deletedplugintypes` object. If the `deprecatedplugintypes` object is now empty, it may be removed entirely from config.
195+
196+
```json title="lib/components.json demonstrating second stage deprecation (deletion) of a plugin type"
197+
{
198+
"plugintypes": {
199+
...
200+
},
201+
"subsystems": {
202+
...
203+
},
204+
"deletedplugintypes": {
205+
"aiplacement": "ai/placement"
206+
}
207+
}
208+
```
209+
210+
Third stage deprecation just removes the plugin type from the `deletedplugintypes` object. If the `deletedplugintypes` object is now empty, it may be removed entirely from config.
211+
212+
```json title="lib/components.json demonstrating final stage deprecation of a plugin type. The process is the same for subplugin types."
213+
{
214+
"plugintypes": {
215+
...
216+
},
217+
"subsystems": {
218+
...
219+
},
220+
}
221+
```
222+
223+
:::
224+
225+
### Deprecating a subplugin type
226+
227+
To mark a subplugin type as deprecated, edit the component's `subplugins.json` file, remove the subplugin type from the `subplugintypes` object and add it to the `deprecatedsubplugintypes` object. The mark a subplugin type for stage 2 deprecation (deletion), edit the same file and move the subplugin type from the `deprecatedsubplugintypes` object to the `deletedsubplugintypes` object.
228+
229+
Following deletion, the plugin/subplugin type can be removed from the respective JSON entirely.
230+
231+
:::info Remember
232+
Don't forget to increment the core version number when marking a plugin/subplugin type for either deprecation or deletion. A version bump isn't needed for final removal.
233+
:::
234+
235+
:::tip Example of subplugin type deprecation config values
236+
237+
To mark a subplugin type as deprecated in a component's `subplugins.json`, the subplugin type should be removed from the `subplugintypes` object, and added to a new `deprecatedsubplugintypes` object.
238+
239+
```json title="mod/lti/db/subplugins.json demonstrating first stage deprecation of a subplugin type"
240+
{
241+
"subplugintypes": {
242+
"ltiservice": "service"
243+
},
244+
"deprecatedsubplugintypes": {
245+
"ltisource": "source"
246+
}
247+
}
248+
```
249+
250+
To mark a subplugin type as deleted in a component's `subplugins.json`, the subplugin type should be removed from the `deprecatedsubplugintypes` object, and added to a new `deletedsubplugintypes` object. If the `deprecatedsubplugintypes` object is now empty, it may be removed entirely from config.
251+
252+
```json title="mod/lti/db/subplugins.json demonstrating second stage deprecation (deletion) of a subplugin type"
253+
{
254+
"subplugintypes": {
255+
"ltiservice": "service"
256+
},
257+
"deletedsubplugintypes": {
258+
"ltisource": "source"
259+
}
260+
}
261+
```
262+
263+
Third stage deprecation just removes the subplugin type from the `deletedsubplugintypes` object. If this object is then empty, it may be removed entirely from config.
264+
265+
```json title="mod/lti/db/subplugins.json demonstrating final stage deprecation of a subplugin type."
266+
{
267+
"subplugintypes": {
268+
"ltiservice": "service"
269+
}
270+
}
271+
```
272+
273+
:::
274+
135275
## See also
136276

137277
- [Guidelines for contributing code](https://docs.moodle.org/dev/Guidelines_for_contributed_code)

‎docs/devupdate.md

+107
Original file line numberDiff line numberDiff line change
@@ -113,3 +113,110 @@ $activity-icon-interactivecontent-bg: #c70827;
113113
Moodle has updated the version of PHPUnit used in core to version 11.4. Some tests may encounter issues as a result.
114114

115115
Please see the [PHPUnit 11 Upgrade Guide](/general/development/tools/phpunit/upgrading-11) for assistance in updating any broken tests.
116+
117+
:::
118+
119+
## Plugin type deprecation
120+
121+
<Since version="5.0" issueNumber="MDL-79843" />
122+
123+
A new process for plugin type and subplugin type deprecation has been introduced.
124+
125+
Using `components.json` or `subplugins.json` plugin types and subplugin types, respectively, can be marked as deprecated or deleted.
126+
127+
:::info
128+
Plugin/subplugin type deprecation doesn't follow the same rules as code deprecation. Core considers deprecated plugins as end-of-life and will omit them from many core APIs. Things like hooks, callbacks and events will not include/call plugins of a deprecated type.
129+
:::
130+
131+
Deprecation follows a 3 stage process:
132+
133+
1. The plugin/subplugin type is marked as deprecated (a core version bump is also required).
134+
2. The plugin/subplugin type is marked as deleted (a core version bump is also required).
135+
3. Final removal of the plugin/subplugin type from the respective config file.
136+
137+
:::info Limitations
138+
Currently, only those plugin types _not_ supporting subplugins can be deprecated.
139+
:::
140+
141+
During first stage deprecation, plugins of the respective type may remain installed, but are deemed end-of-life. This stage gives admins time to remove the affected plugins from the site, or migrate them to their replacement plugins.
142+
143+
In second stage deprecation (deletion), if any affected plugins are still present (i.e. have not been removed/uninstalled yet) site upgrade will be blocked. These plugins must be removed at this time to continue.
144+
145+
In final stage deprecation (final removal), the relevant config changes supporting first and second stage deprecation can be removed from the respective config files. This removes the last reference to these plugin/subplugin types.
146+
147+
:::tip Example of the new plugin/subplugin type deprecation config values
148+
149+
To mark a plugin type as deprecated in `components.json`, the plugin type should be removed from the `plugintypes` object, and added to a new `deprecatedplugintypes` object.
150+
151+
```json title="lib/components.json demonstrating first stage deprecation of a plugin type"
152+
{
153+
"plugintypes": {
154+
...
155+
},
156+
"subsystems": {
157+
...
158+
},
159+
"deprecatedplugintypes": {
160+
"aiplacement": "ai/placement"
161+
}
162+
}
163+
```
164+
165+
To mark a subplugin type as deprecated in a component's `subplugins.json`, the subplugin type should be removed from the `subplugintypes` object, and added to a new `deprecatedsubplugintypes` object.
166+
167+
```json title="mod/lti/db/subplugins.json demonstrating first stage deprecation of a subplugin type"
168+
{
169+
"subplugintypes": {
170+
},
171+
"deprecatedsubplugintypes": {
172+
"ltiservice": "service",
173+
"ltisource": "source"
174+
}
175+
}
176+
```
177+
178+
To mark a plugin type as deleted in `components.json`, the plugin type should be removed from the `deprecatedplugintypes` object, and added to a new `deletedplugintypes` object.
179+
180+
```json title="lib/components.json demonstrating second stage deprecation (deletion) of a plugin type"
181+
{
182+
"plugintypes": {
183+
...
184+
},
185+
"subsystems": {
186+
...
187+
},
188+
"deprecatedplugintypes": {
189+
},
190+
"deletedplugintypes": {
191+
"aiplacement": "ai/placement"
192+
}
193+
}
194+
```
195+
196+
To mark a subplugin type as deleted in a component's `subplugins.json`, the subplugin type should be removed from the `deprecatedsubplugintypes` object, and added to a new `deletedsubplugintypes` object.
197+
198+
```json title="mod/lti/db/subplugins.json demonstrating second stage deprecation (deletion) of a subplugin type"
199+
{
200+
"deprecatedsubplugintypes": {
201+
},
202+
"deletedsubplugintypes": {
203+
"ltiservice": "service",
204+
"ltisource": "source"
205+
}
206+
}
207+
```
208+
209+
Third stage deprecation just removes the plugin/subplugin type from the respective `deletedplugintypes` or `deletedsubplugintypes` objects. If these objects are empty, they may also be removed entirely.
210+
211+
```json title="lib/components.json demonstrating final stage deprecation of a plugin type. The process is the same for subplugin types."
212+
{
213+
"plugintypes": {
214+
...
215+
},
216+
"subsystems": {
217+
...
218+
},
219+
}
220+
```
221+
222+
:::

‎general/development/policies/deprecation/index.md

+1
Original file line numberDiff line numberDiff line change
@@ -290,6 +290,7 @@ Named parameter arguments are available from PHP 8.0 onwards.
290290
- [Deprecation attributes](/docs/apis/core/deprecation/)
291291
- [External functions deprecation](/docs/apis/subsystems/external/writing-a-service#deprecation)
292292
- [Capabilities deprecation](/docs/apis/subsystems/access#deprecating-a-capability)
293+
- [Plugin type deprecation](/docs/apis/plugintypes#plugin-type-deprecation)
293294
- [Icon deprecation](./icon-deprecation.md)
294295
- [SCSS deprecation](./scss-deprecation.md)
295296
- [Behat step definition deprecation](../../tools/behat/writing.md#deprecating-a-step-definition)

‎general/development/tools/metadata/index.md

+4
Original file line numberDiff line numberDiff line change
@@ -39,6 +39,8 @@ The name and location on disk of every plugin type, and subsystem is described i
3939

4040
</details>
4141

42+
Plugin types may also be marked as deprecated in this metadata. For more information, see [Plugin type deprecation](/docs/apis/plugintypes#plugin-type-deprecation).
43+
4244
## Subplugins
4345

4446
Any plugin which supports subplugins must describe its subplugin types by name and path in that plugins `db/subplugins.json` location.
@@ -48,6 +50,8 @@ This file requires that subplugins be specified as a set of key and value pairs
4850
- The name is the used as a prefix for all namespaces.
4951
- The path is the path that the plugins exist within.
5052

53+
Subplugin types may also be marked as deprecated in this metadata. For more information, see [Plugin type deprecation](/docs/apis/plugintypes#plugin-type-deprecation).
54+
5155
In the following example the subplugins used in `mod_quiz` are described.
5256

5357
The Quiz activity module is located in `mod/quiz`. It has two subplugin types, `quiz`, and `quizaccess` which are located in `mod/quiz/report`, and `mod/quiz/accessrule` respectively.

0 commit comments

Comments
 (0)