Add deprecation policy for low-adoption features

[Copilot]

Establishes formal criteria and process for deprecating low-adoption schema fields and features, supporting removal decisions for features below 3% usage.

Changes

DEPRECATION_POLICY.md - New 416-line policy document:

• Criteria: Usage thresholds (<1%, 1-3%, >3%), maintenance burden, alternatives, strategic fit
• Process: 4-phase workflow (Evaluation → Announcement → Grace Period → Removal)
• Communication: Requirements for GitHub discussions, CHANGELOG, schema warnings, runtime warnings, docs
• Grace periods:
  • CLI: 3 months / 2 minor releases
  • Schema high usage (>3%): 6 months / 3 minor releases
  • Schema low usage (<1%): 3 months / 2 minor releases
  • Dead code: 1 month / 1 minor release
  • Security: immediate removal allowed
• v2.0 planning: Milestone tracking, bundling strategy, release checklist
• Migration support: Required template with before/after examples
• 3 detailed examples with timelines for different deprecation scenarios

CONTRIBUTING.md - Added deprecation policy references:

• New section after Testing
• Cross-reference in CLI Breaking Changes section

README.md - Added policy link in Contributing section

Usage Example

Deprecating a low-adoption schema field:

### Deprecated

- **`old-field` in workflow schema**: Deprecated, will be removed in v2.0. Use `new-field` instead. Migration guide: [link]

Grace period: 3 months (2 minor releases) → Removal in v2.0

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[plan] Create deprecation policy for low-adoption features</issue_title>
<issue_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

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

Comments on the Issue (you are @copilot in this section)

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

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.