Skip to content

Commit 187ed11

Browse files
andrewnicolsandrewnicols
authored
Merge pull request #1247 from snake/MDL-79843-main
[docs] document plugin/subplugin type deprecation
2 parents 14852eb + a071d4f commit 187ed11

File tree

4 files changed

+173
-0
lines changed

4 files changed

+173
-0
lines changed

‎docs/apis/plugintypes/index.md

+160
Original file line numberDiff line numberDiff line change
@@ -132,6 +132,166 @@ 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 and subplugin type deprecation differs slightly to the 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, and-so-on.
146+
In the case of subplugins, the subplugin owner (the component which the subplugin belongs to), **must** have been updated to remove or replace all references to the subplugins 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+
152+
Whilst both plugin and subplugin types can be deprecated, only those plugin types which do _not_ support subplugins can be deprecated.
153+
154+
:::
155+
156+
### Deprecation process
157+
158+
Deprecation follows a 3 stage process:
159+
160+
1. The plugin/subplugin type is marked as deprecated (a core version bump is also required).
161+
2. The plugin/subplugin type is marked as deleted (a core version bump is also required).
162+
3. Final removal of the plugin/subplugin type from the respective config file.
163+
164+
#### First stage deprecation
165+
166+
During first stage deprecation, plugins of the respective type may remain installed, but are deemed end-of-life.
167+
168+
This stage gives administrators time to remove the affected plugins from the site, or migrate them to their replacement plugins.
169+
170+
#### Second stage deprecation
171+
172+
The second stage deprecation is the deletion phase.
173+
174+
If any affected plugins are still present (that is any which have not been uninstalled or migrated yet), the site upgrade will be blocked.
175+
176+
These plugins **must** be removed before continuing with site upgrade.
177+
178+
#### Final deprecation
179+
180+
In the final deprecation stage the relevant configuration 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.
181+
182+
### Deprecating a plugin type
183+
184+
The first phase of plugin type deprecation involves describing the plugin in the `deprecatedplugintypes` configuration in `lib/components.json`. The plugin type must also be removed from the `plugintypes` object.
185+
186+
The second phase of plugin type deprecation involves moving the entry from the `deprecatedplugintypes` object to the `deletedplugintypes` object.
187+
188+
:::info Remember
189+
190+
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.
191+
192+
:::
193+
194+
:::tip Example of plugin type deprecation config values
195+
196+
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.
197+
198+
```json title="lib/components.json demonstrating first stage deprecation of a plugin type"
199+
{
200+
"plugintypes": {
201+
...
202+
},
203+
"subsystems": {
204+
...
205+
},
206+
"deprecatedplugintypes": {
207+
"aiplacement": "ai/placement"
208+
}
209+
}
210+
```
211+
212+
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.
213+
214+
```json title="lib/components.json demonstrating second stage deprecation (deletion) of a plugin type"
215+
{
216+
"plugintypes": {
217+
...
218+
},
219+
"subsystems": {
220+
...
221+
},
222+
"deletedplugintypes": {
223+
"aiplacement": "ai/placement"
224+
}
225+
}
226+
```
227+
228+
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.
229+
230+
```json title="lib/components.json demonstrating final stage deprecation of a plugin type. The process is the same for subplugin types."
231+
{
232+
"plugintypes": {
233+
...
234+
},
235+
"subsystems": {
236+
...
237+
},
238+
}
239+
```
240+
241+
:::
242+
243+
### Deprecating a subplugin type
244+
245+
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.
246+
247+
Following deletion, the plugin/subplugin type can be removed from the respective JSON entirely.
248+
249+
:::info Remember
250+
251+
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.
252+
253+
:::
254+
255+
:::tip Example of subplugin type deprecation config values
256+
257+
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.
258+
259+
```json title="mod/lti/db/subplugins.json demonstrating first stage deprecation of a subplugin type"
260+
{
261+
"subplugintypes": {
262+
"ltiservice": "service"
263+
},
264+
"deprecatedsubplugintypes": {
265+
"ltisource": "source"
266+
}
267+
}
268+
```
269+
270+
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.
271+
272+
```json title="mod/lti/db/subplugins.json demonstrating second stage deprecation (deletion) of a subplugin type"
273+
{
274+
"subplugintypes": {
275+
"ltiservice": "service"
276+
},
277+
"deletedsubplugintypes": {
278+
"ltisource": "source"
279+
}
280+
}
281+
```
282+
283+
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.
284+
285+
```json title="mod/lti/db/subplugins.json demonstrating final stage deprecation of a subplugin type."
286+
{
287+
"subplugintypes": {
288+
"ltiservice": "service"
289+
}
290+
}
291+
```
292+
293+
:::
294+
135295
## See also
136296

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

‎docs/devupdate.md

+8
Original file line numberDiff line numberDiff line change
@@ -113,3 +113,11 @@ $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. See [the Plugin Type deprecation](./apis/plugintypes/index.md#deprecating-a-plugin-type) and [Subplugin deprecation](./apis/plugintypes/index.md#deprecating-a-subplugin-type) documentation for further information.

‎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)