From b6cc907556a5176f785e7ccf004e3bea1df6f2a7 Mon Sep 17 00:00:00 2001 From: Andrew Nicols Date: Tue, 1 Apr 2025 16:19:01 +0800 Subject: [PATCH] [docs] Clarify meaning of public for deprecation policies --- general/development/policies/deprecation/index.md | 13 ++++++++++++- 1 file changed, 12 insertions(+), 1 deletion(-) diff --git a/general/development/policies/deprecation/index.md b/general/development/policies/deprecation/index.md index 269cb37c66..11dcd18ffe 100644 --- a/general/development/policies/deprecation/index.md +++ b/general/development/policies/deprecation/index.md @@ -18,12 +18,23 @@ In an open source project, the end use of the codebase varies. People may have c ## What is Moodle's deprecation policy? -- Deprecations should only be on main, not on stables (exceptions may be made for some external service integrations) +- Deprecations should only be on the `main` branch, not on stables (exceptions may be made for some external service integrations) - Deprecations apply to all public APIs, classes, and files. - Removal of a function, class, or file may only be considered after a minimum of 4 major releases since the deprecation. Example: anything deprecated in 3.2 means that it will be removed in 3.6 - All deprecations should emit debugging notices where possible - All deprecations should be noted with an [upgrade note](../../upgradenotes.md). +:::danger What does it mean for an API to be considered "Public" + +When we talk about Public APIs in Moodle, we are not referring to the `public` keyword in the method definition. + +Instead we are considering how that API feature is used. Is that API feature intended to be, or is there a reasonable expectation that it may be, consumed in some reasonable way including: + +- being called or accessed externally; or +- being overridden in a class OOP sense. + +::: + ## Moodle Core deprecation process Once it is decided that a function should be deprecated, a two-step process should be followed.