liveBook · Manning

Deprecated feature

As explained in Building User-Friendly DSLs

The process of marking a language feature as discouraged or obsolete while retaining it temporarily for dependent content.

A deprecated feature is a DSL concept or property marked for removal while dependent domain knowledge remains usable. Deprecation protects that knowledge by warning domain experts and providing a migration path before technical removal. section 10.3.3

A practical deprecation process should:

  • Report every use through a constraint whose issue explains the feature’s deprecated status, reason, removal timeline, and supported replacement. section 10.3.3
  • Begin at least several releases before removal, initially using warning severity and later increasing it to error severity. section 10.3.3
  • Remove remaining concept instances or property settings through an AST migration, including references to removed concept instances. section 10.3.3
  • Delete the deprecated feature’s remaining implementation traces only after DSL content no longer uses it. section 10.3.3

Replacing a deprecated DSL property

A constraint reports each setting of the old property. Its message explains why the property is deprecated and how to express the same domain knowledge with supported constructs. An AST migration then transforms remaining content before the implementation deletes the property. section 10.3.3

How Building User-Friendly DSLs covers it

How deep it goes
Explains warnings, migration guidance, severity escalation, AST cleanup, and implementation deletion, but not migration code.
Examples
Uses deprecated concepts or properties, diagnostic issues, warning-to-error escalation, and AST migrations as concrete artifacts.
What it assumes
Assumes DSL content, domain knowledge, concepts, properties, constraints, and AST migrations are available for change management.
What you can do after
Operate/configure a staged deprecation process that warns users, guides replacement, migrates content, and removes implementation traces.
How it connects
Connects deprecation with domain-specific languages, constraints, AST migration, version IDs, and structural change.
Cover of Building User-Friendly DSLs
liveBookmanning.com
Read Building User-Friendly DSLs on liveBook Get the book at manning.com

Related concepts

This explainer was generated by Manning's knowledge graph from the text of Building User-Friendly DSLs. The section links point to the parts of the book it draws on.