-
Notifications
You must be signed in to change notification settings - Fork 36
Closed as not planned
Labels
ai-generateddocumentationImprovements or additions to documentationImprovements or additions to documentationplanpolicy
Description
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
- Create
DEPRECATION_POLICY.mdwith 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
- Define adoption thresholds:
- <1% usage: Candidate for immediate deprecation
- 1-3% usage: Monitor and consider deprecation
-
3% usage: Keep or improve discoverability
- Establish communication requirements:
- GitHub discussions announcement
- CHANGELOG entry
- Schema deprecation warnings
- Migration guide
- 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
Copilot
Metadata
Metadata
Labels
ai-generateddocumentationImprovements or additions to documentationImprovements or additions to documentationplanpolicy