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.

← Older revision		Revision as of 11:42, 11 April 2026
Line 1:		Line 1:
	= Revised Deprecation Policy =		== Revised Deprecation Policy ==

	== Goals ==		== Goals ==
Line 7:		Line 7:

	== Deprecation Lifecycle ==		== 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 ==		== Support for UMC Authors ==
Line 35:		Line 35:
	== Refuting Common Objections ==		== Refuting Common Objections ==
	* '''“Deprecation messages are helpful.”'''		* '''“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 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.”'''		* '''“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 ==		== 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.		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