[docs] Document the final removal process #1315
Conversation
✅ Deploy Preview for moodledevdocs ready!
To edit notification comments on pull requests, go to your Netlify site configuration. |
There was a problem hiding this comment.
Pull Request Overview
This PR updates the deprecation policy documentation to clearly outline the final removal process with improved structure and examples.
- Clarified conditions for deprecations on the main branch
- Revised formatting and phrasing for deprecation steps and code examples
- Added a new section detailing the removal process
andrewnicols
force-pushed
the
deprecationRemovalsAndClarifications
branch
from
34c8e5f to
114d779
Compare
There was a problem hiding this comment.
Pull Request Overview
This PR updates the deprecation policy documentation to clearly outline the process for final removal of deprecated features. Key changes include:
- Expanded details on when deprecations can be applied, including exceptions for external integrations, irreparable feature breaks, and security issues.
- Revised and restructured examples demonstrating both debugging and deprecation API usage.
- Clarified the removal process with a new Step 3 section and modified guidelines on handling function versus method signatures.
Comments suppressed due to low confidence (1)
general/development/policies/deprecation/index.md:172
- [nitpick] There appears to be a distinction between method signatures and function signatures in this section. It would help to add additional clarification to explain why function signatures may be removed while method signatures must remain unchanged.
Method signatures **must not change**, that is:
andrewnicols
force-pushed
the
deprecationRemovalsAndClarifications
branch
from
114d779 to
17ec0bb
Compare
There was a problem hiding this comment.
Pull Request Overview
This PR updates the deprecation policy documentation to clarify the final removal process and refine guidelines surrounding deprecation stages and method/function signature changes. Key changes include:
- Splitting deprecation into three clear stages (Initial deprecation, Final deprecation, and Removal).
- Updating tabbed examples and code snippets for both debugging notices and the \core\deprecation API.
- Revising the policy on method versus function signature changes with an accompanying explanatory info section.
| @@ -41,13 +47,13 @@ Once it is decided that a function should be deprecated, a two-step process shou | |||
|
|
|||
There was a problem hiding this comment.
https://github.com/moodle/devdocs/pull/1315/files#diff-0329f1a6ba03aa03e622145c91413b7e0d55a262b5e3cd200b619496a83d0c3bR46 mentions "two-step process". I think we should update to "three-step process"
| - Functions deprecated in Moodle 4.5 (LTS) will be up for final deprecation in Moodle 6.0 (the first release for Series 6 right after the Moodle 5.3 (LTS) release). | ||
| </ValidExample> | ||
|
|
||
| #### Procedure | ||
|
|
||
| - When a function undergoes final deprecation, all content of the function should be removed. In the skeleton that remains, an error statement should be included that indicates that the function cannot be used anymore. You can also direct developers to the new function(s) in this message. | ||
| - When a function undergoes final deprecation, all content of the function should be removed. In the skeleton that remains, an error statement should be included that indicates that the function can not be used anymore. You can also direct developers to the new function(s) in this message. |
There was a problem hiding this comment.
I think 'cannot' is more correct than 'can not' here. So, pity to see you changing it the 'wrong' way: https://www.google.com/search?client=firefox-b-e&channel=entpr&q=cannot+vs+can+not. (Sorry, grammar pedant.)
There was a problem hiding this comment.
More importantly "You can also direct developers to ...". I would say "can (and should)" just to re-inforce a point made elsewhere on this page.
No description provided.