[docs] Further clarify final deprecation procedure #1373
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Signed-off-by: Daniel Ziegenberg <[email protected]>
✅ Deploy Preview for moodledevdocs ready!Built without sensitive environment variables
To edit notification comments on pull requests, go to your Netlify project configuration. |
There was a problem hiding this comment.
Pull Request Overview
Clarify the final deprecation procedure by updating the documentation to specify how to direct developers to replacements and handle typed returns.
- Add conditional guidance on including replacement references in error messages.
- Specify return statement requirements for functions with typed returns.
Comments suppressed due to low confidence (2)
general/development/policies/deprecation/index.md:139
- [nitpick] This sentence is a bit long and the conditional clause could be clearer; consider rephrasing to: "If the deprecated function has a replacement, update the error message to direct developers to the new function(s)."
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 should also direct developers to the new function(s) in this message, if the deprecated function has been replaced with a new function.
general/development/policies/deprecation/index.md:178
- [nitpick] The phrase "return accordingly" is vague; consider explicitly stating: "If the signature declares a return type, include a return statement compatible with that type; otherwise omit the return statement."
If the method or function has a typed return, it needs to return accordingly, otherwise no return is required.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
If the method or function has a typed return, it needs to return accordingly, otherwise no return is required.
See this comment for reference.