[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:
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.
andrewnicols
force-pushed
the
deprecationRemovalsAndClarifications
branch
from
17ec0bb to
3ac272a
Compare
|
Thanks both, I've updated the text for those points. |
There was a problem hiding this comment.
Copilot reviewed 1 out of 1 changed files in this pull request and generated 1 comment.
Comments suppressed due to low confidence (1)
general/development/policies/deprecation/index.md:160
- [nitpick] The relabeling and ordering of the TabItems between the 'core_deprecation' and 'debugging' examples appear inconsistent compared to the previous version. Please verify that each tab is correctly named and placed to avoid confusion.
+<TabItem value="debugging" label="Deprecations using debugging">
| - Function signatures _may_ be removed, that is: | ||
| - all parameters may be removed; and | ||
| - and return type declaration may be removed. |
There was a problem hiding this comment.
There is a contradiction between the bullet stating that function signatures may be removed and the info box later indicating that modifying method signatures is no longer permitted. Please clarify which policy should apply.
| - Function signatures _may_ be removed, that is: | |
| - all parameters may be removed; and | |
| - and return type declaration may be removed. | |
| - Function signatures **must not change**, that is: | |
| - keep any existing parameters; and | |
| - keep any existing return type. |
Copilot is powered by AI, so mistakes are possible. Review output carefully before use.
No description provided.