Bssarkar: draft deprecation policy

2026-04-11T11:42:46Z

draft deprecation policy

Bssarkar: new deprecation policy

2026-04-11T11:38:04Z

new deprecation policy

New page

= Revised Deprecation Policy =

== Goals ==
* Keep the codebase clean and maintainable.
* Provide clear expectations for UMC authors.
* Ensure deprecation messages remain credible by tying them to actual removal.

== Deprecation Lifecycle ==
# '''Marking Deprecated'''
* When an API or feature is obsolete, mark it deprecated immediately.
* Deprecation message must include: version deprecated, recommended replacement, and planned removal version.

# '''Minimum Deprecation Period'''
* Deprecated features remain for one stable release cycle.
* During this period, warnings are shown with migration guidance.

# '''Sunset Clause'''
* After one stable release, the feature is scheduled for removal in the next release.
* No indefinite wrappers. “Deprecated” always means “will be removed.”

# '''Removal'''
* Features are removed as scheduled, even if some UMCs still rely on them.
* Routine cleanup is a valid reason for removal — no need to wait for a blocking obstacle.

== Support for UMC Authors ==
* '''Migration Tools:''' wmllint/wmlscope must be updated to suggest or apply fixes automatically.
* '''Documentation:''' Wiki entries must clearly list deprecated features, replacements, and removal timelines.
* '''Major Versions:''' For large‑scale removals, major version bumps (e.g., 2.0) provide a clean slate.

== Enforcement ==
* Deprecation without removal is not allowed.
* Consensus is required to '''delay''' removal, not to perform it.
* Developers are empowered to perform routine cleanup without prolonged debate.

== Refuting Common Objections ==
* '''“Deprecation messages are helpful.”'''
– True, but only if they are credible. If removal never happens, the message is misleading.
– Warnings that never resolve train UMC authors to ignore them, undermining trust in tools.
– Messages stay helpful only when backed by action: clear timelines and actual removal.

* '''“Wrappers are harmless.”'''
– Wrappers accumulate and clutter the codebase, making it harder to maintain.
– They give a false sense of safety while delaying modernization.
– Routine cleanup prevents technical debt from piling up.

* '''“UMC authors need stability.”'''
– Stability comes from predictability, not indefinite legacy.
– Clear removal timelines and migration tools give authors confidence.
– Indefinite deprecation leaves authors in limbo, forcing piecemeal porting anyway.

== Summary ==
This policy makes deprecation meaningful. UMC authors get clear timelines and migration guidance, while developers can keep the codebase lean. Wrappers and indefinite deprecation are eliminated, ensuring that “deprecated” is a real lifecycle stage rather than a cosmetic label.

@@ Line 1: / Line 1: @@
-= Revised Deprecation Policy =
+== Revised Deprecation Policy ==
 == Goals ==
@@ Line 7: / Line 7: @@
 == Deprecation Lifecycle ==
-# '''Marking Deprecated'''
+=== Marking Deprecated ===
-   * When an API or feature is obsolete, mark it deprecated immediately.
+* When an API or feature is obsolete, mark it deprecated immediately.
-   * Deprecation message must include: version deprecated, recommended replacement, and planned removal version.
+* Deprecation message must include: version deprecated, recommended replacement, and planned removal version.
-# '''Minimum Deprecation Period'''
+=== Minimum Deprecation Period ===
-   * Deprecated features remain for one stable release cycle.
+* Deprecated features remain for one stable release cycle.
-   * During this period, warnings are shown with migration guidance.
+* During this period, warnings are shown with migration guidance.
-# '''Sunset Clause'''
+=== Sunset Clause ===
-   * After one stable release, the feature is scheduled for removal in the next release.
+* After one stable release, the feature is scheduled for removal in the next release.
-   * No indefinite wrappers. “Deprecated” always means “will be removed.”
+* No indefinite wrappers. “Deprecated” always means “will be removed.”
-# '''Removal'''
+=== Removal ===
-   * Features are removed as scheduled, even if some UMCs still rely on them.
+* Features are removed as scheduled, even if some UMCs still rely on them.
-   * Routine cleanup is a valid reason for removal — no need to wait for a blocking obstacle.
+* Routine cleanup is a valid reason for removal — no need to wait for a blocking obstacle.
 == Support for UMC Authors ==
@@ Line 35: / Line 35: @@
 == Refuting Common Objections ==
 * '''“Deprecation messages are helpful.”'''
-  – True, but only if they are credible. If removal never happens, the message is misleading.
+** True, but only if they are credible. If removal never happens, the message is misleading.
-  – Warnings that never resolve train UMC authors to ignore them, undermining trust in tools.
+** Warnings that never resolve train UMC authors to ignore them, undermining trust in tools.
-  – Messages stay helpful only when backed by action: clear timelines and actual removal.
+** Messages stay helpful only when backed by action: clear timelines and actual removal.
 * '''“Wrappers are harmless.”'''
-  – Wrappers accumulate and clutter the codebase, making it harder to maintain.
+** Wrappers accumulate and clutter the codebase, making it harder to maintain.
-  – They give a false sense of safety while delaying modernization.
+** They give a false sense of safety while delaying modernization.
-  – Routine cleanup prevents technical debt from piling up.
+** Routine cleanup prevents technical debt from piling up.
 * '''“UMC authors need stability.”'''
-  – Stability comes from predictability, not indefinite legacy.
+** Stability comes from predictability, not indefinite legacy.
-  – Clear removal timelines and migration tools give authors confidence.
+** Clear removal timelines and migration tools give authors confidence.
-  – Indefinite deprecation leaves authors in limbo, forcing piecemeal porting anyway.
+** Indefinite deprecation leaves authors in limbo, forcing piecemeal porting anyway.
 == Summary ==
 This policy makes deprecation meaningful. UMC authors get clear timelines and migration guidance, while developers can keep the codebase lean. Wrappers and indefinite deprecation are eliminated, ensuring that “deprecated” is a real lifecycle stage rather than a cosmetic label.

User:Bssarkar - Revision history

Bssarkar: draft deprecation policy

Bssarkar: new deprecation policy