Skip to content

[plan] Create deprecation policy for low-adoption features #8379

@github-actions

Description

@github-actions

Objective

Create a formal deprecation policy and process for handling low-adoption or unused schema fields.

Context

The analysis identified 5 low-adoption features and 1 dead code field. The project needs a clear process for:

  • When to deprecate features
  • How to communicate deprecation to users
  • Migration timeline requirements
  • Breaking change release planning

Currently there's no documented process, making it difficult to make deprecation decisions consistently.

Approach

  1. Create DEPRECATION_POLICY.md with sections:
    • Criteria for deprecation: Usage thresholds, maintenance burden, alternatives
    • Deprecation process: Timeline, communication, warnings
    • Breaking change releases: Major version requirements, bundling multiple changes
    • Migration support: How to help users migrate away from deprecated features
    • Grace periods: Minimum time between deprecation announcement and removal
  2. Define adoption thresholds:
    • <1% usage: Candidate for immediate deprecation
    • 1-3% usage: Monitor and consider deprecation
    • 3% usage: Keep or improve discoverability

  3. Establish communication requirements:
    • GitHub discussions announcement
    • CHANGELOG entry
    • Schema deprecation warnings
    • Migration guide
  4. Document the v2.0 planning process for bundling breaking changes

Files to Modify

  • Create: DEPRECATION_POLICY.md (new policy document)
  • Update: CONTRIBUTING.md (reference deprecation policy)
  • Update: README.md (add link to policy)
  • Update: ARCHITECTURE.md (reference policy in low-adoption section)

Acceptance Criteria

  • DEPRECATION_POLICY.md defines clear criteria
  • Process covers deprecation announcement through removal
  • Usage thresholds documented (1%, 3% breakpoints)
  • Grace period requirements specified
  • Migration support process defined
  • Breaking change release process documented
  • Linked from relevant documentation

Reference

This supports the recommendation to deprecate low-adoption fields if they remain below 3% usage by Q2 2025.
Related to #8374

AI generated by Plan Command for discussion #8372

Metadata

Metadata

Type

No type

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions