569 lines
12 KiB
Markdown
569 lines
12 KiB
Markdown
---
|
|
description: Phased feature sunset workflow with migration guidance
|
|
---
|
|
|
|
<!--
|
|
ATTRIBUTION CHAIN:
|
|
1. Original methodology: spec-kit-extensions by Marty Bonacci (2025)
|
|
2. Adapted: SpecLab plugin by Marty Bonacci & Claude Code (2025)
|
|
3. Based on: GitHub spec-kit | MIT License
|
|
-->
|
|
|
|
## User Input
|
|
|
|
```text
|
|
$ARGUMENTS
|
|
```
|
|
|
|
You **MUST** consider the user input before proceeding (if not empty).
|
|
|
|
## Goal
|
|
|
|
Execute phased deprecation workflow to safely sunset features while providing migration guidance to users.
|
|
|
|
**Key Principles**:
|
|
1. **Phased Approach**: Announce → Migrate → Remove
|
|
2. **Migration Guidance**: Provide clear alternatives
|
|
3. **User Support**: Help users migrate
|
|
4. **Track Adoption**: Monitor migration progress
|
|
5. **Safe Removal**: Only remove when migration complete
|
|
|
|
**Phases**: Announce deprecation, user migration support, feature removal
|
|
|
|
**Coverage**: Addresses ~5% of development work (feature evolution)
|
|
|
|
---
|
|
|
|
## Smart Integration
|
|
|
|
```bash
|
|
SPECSWARM_INSTALLED=$(claude plugin list | grep -q "specswarm" && echo "true" || echo "false")
|
|
SPECTEST_INSTALLED=$(claude plugin list | grep -q "spectest" && echo "true" || echo "false")
|
|
|
|
if [ "$SPECTEST_INSTALLED" = "true" ]; then
|
|
ENABLE_HOOKS=true
|
|
ENABLE_METRICS=true
|
|
fi
|
|
```
|
|
|
|
---
|
|
|
|
## Execution Steps
|
|
|
|
### 1. Discover Deprecation Context
|
|
|
|
```bash
|
|
REPO_ROOT=$(git rev-parse --show-toplevel 2>/dev/null || pwd)
|
|
CURRENT_BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null)
|
|
DEPRECATE_NUM=$(echo "$CURRENT_BRANCH" | grep -oE 'deprecate/([0-9]{3})' | grep -oE '[0-9]{3}')
|
|
|
|
if [ -z "$DEPRECATE_NUM" ]; then
|
|
echo "📉 Deprecate Workflow"
|
|
echo "Provide deprecation number:"
|
|
read -p "Deprecation number: " DEPRECATE_NUM
|
|
DEPRECATE_NUM=$(printf "%03d" $DEPRECATE_NUM)
|
|
fi
|
|
|
|
# Source features location helper
|
|
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
|
|
PLUGIN_DIR="$(dirname "$SCRIPT_DIR")"
|
|
source "$PLUGIN_DIR/lib/features-location.sh"
|
|
|
|
# Initialize features directory
|
|
ensure_features_dir "$REPO_ROOT"
|
|
|
|
FEATURE_DIR="${FEATURES_DIR}/${DEPRECATE_NUM}-deprecate"
|
|
mkdir -p "$FEATURE_DIR"
|
|
|
|
DEPRECATE_SPEC="${FEATURE_DIR}/deprecate.md"
|
|
MIGRATION_GUIDE="${FEATURE_DIR}/migration-guide.md"
|
|
TASKS_FILE="${FEATURE_DIR}/tasks.md"
|
|
```
|
|
|
|
---
|
|
|
|
### 2. Identify Feature to Deprecate
|
|
|
|
```
|
|
📉 Feature Deprecation
|
|
|
|
Which feature are you deprecating?
|
|
[User input or scan codebase]
|
|
|
|
Feature to deprecate: [name]
|
|
Reason for deprecation: [reason]
|
|
Alternative/replacement: [what users should use instead]
|
|
```
|
|
|
|
---
|
|
|
|
### 3. Create Deprecation Specification
|
|
|
|
```markdown
|
|
# Deprecation ${DEPRECATE_NUM}: [Feature Name]
|
|
|
|
**Status**: Active
|
|
**Created**: YYYY-MM-DD
|
|
**Feature**: [Feature to deprecate]
|
|
**Replacement**: [Alternative feature/approach]
|
|
|
|
---
|
|
|
|
## Deprecation Rationale
|
|
|
|
**Why Deprecating**:
|
|
- Reason 1
|
|
- Reason 2
|
|
- Reason 3
|
|
|
|
**Timeline Decision**: [Why now?]
|
|
|
|
---
|
|
|
|
## Current Usage Analysis
|
|
|
|
**Users Affected**: [Estimated N users/systems]
|
|
**Usage Patterns**: [How is it currently used?]
|
|
|
|
**Dependencies**:
|
|
| Dependent System | Usage Level | Migration Complexity |
|
|
|------------------|-------------|----------------------|
|
|
| [System 1] | [High/Med/Low] | [High/Med/Low] |
|
|
|
|
---
|
|
|
|
## Replacement Strategy
|
|
|
|
**Recommended Alternative**: [Feature/approach]
|
|
|
|
**Why Better**:
|
|
- Benefit 1
|
|
- Benefit 2
|
|
|
|
**Migration Effort**: [Low/Medium/High]
|
|
**Migration Time Estimate**: [timeframe per user]
|
|
|
|
---
|
|
|
|
## Deprecation Timeline
|
|
|
|
### Phase 1: Announcement (Month 1)
|
|
**Duration**: [timeframe]
|
|
**Activities**:
|
|
- [ ] Announce deprecation publicly
|
|
- [ ] Add deprecation warnings to feature
|
|
- [ ] Publish migration guide
|
|
- [ ] Email affected users
|
|
- [ ] Update documentation
|
|
|
|
**Deliverables**:
|
|
- Deprecation announcement
|
|
- Migration guide
|
|
- Updated docs
|
|
|
|
---
|
|
|
|
### Phase 2: Migration Support (Months 2-3)
|
|
**Duration**: [timeframe]
|
|
**Activities**:
|
|
- [ ] Monitor adoption of alternative
|
|
- [ ] Provide migration support to users
|
|
- [ ] Track usage of deprecated feature
|
|
- [ ] Address migration blockers
|
|
- [ ] Send migration reminders
|
|
|
|
**Success Criteria**:
|
|
- ≥80% of users migrated to alternative
|
|
- No critical dependencies remaining
|
|
|
|
---
|
|
|
|
### Phase 3: Removal (Month 4+)
|
|
**Duration**: [timeframe]
|
|
**Activities**:
|
|
- [ ] Final migration reminder (2 weeks notice)
|
|
- [ ] Disable feature in production
|
|
- [ ] Remove code
|
|
- [ ] Cleanup tests and documentation
|
|
- [ ] Archive feature artifacts
|
|
|
|
**Prerequisites**:
|
|
- ≥90% user migration
|
|
- All critical dependencies resolved
|
|
- Stakeholder approval
|
|
|
|
---
|
|
|
|
## Migration Blockers
|
|
|
|
**Known Blockers**:
|
|
| Blocker | Impact | Resolution Plan |
|
|
|---------|--------|-----------------|
|
|
| [Blocker 1] | [High/Med/Low] | [How to resolve] |
|
|
|
|
---
|
|
|
|
## Communication Plan
|
|
|
|
**Channels**:
|
|
- [ ] Blog post / changelog
|
|
- [ ] Email to affected users
|
|
- [ ] In-app deprecation warning
|
|
- [ ] Documentation update
|
|
- [ ] Support ticket template
|
|
|
|
**Messaging**:
|
|
- Clear deprecation timeline
|
|
- Migration guide link
|
|
- Support resources
|
|
- Benefits of alternative
|
|
|
|
---
|
|
|
|
## Rollback Plan
|
|
|
|
**If Migration Fails**:
|
|
- Extend timeline
|
|
- Provide additional support resources
|
|
- Reconsider deprecation if alternative insufficient
|
|
|
|
---
|
|
|
|
## Success Metrics
|
|
|
|
| Metric | Target | Current |
|
|
|--------|--------|---------|
|
|
| User Migration Rate | ≥90% | [%] |
|
|
| Alternative Adoption | ≥80% | [%] |
|
|
| Support Tickets | <10 | [N] |
|
|
| Migration Blockers | 0 | [N] |
|
|
|
|
---
|
|
|
|
## Metadata
|
|
|
|
**Workflow**: Deprecate (Phased Sunset)
|
|
**Created By**: SpecLab Plugin v1.0.0
|
|
```
|
|
|
|
Write to `$DEPRECATE_SPEC`.
|
|
|
|
---
|
|
|
|
### 4. Create Migration Guide
|
|
|
|
```markdown
|
|
# Migration Guide: Deprecation ${DEPRECATE_NUM}
|
|
|
|
**Feature Deprecated**: [Feature name]
|
|
**Recommended Alternative**: [Alternative]
|
|
**Migration Deadline**: [Date]
|
|
|
|
---
|
|
|
|
## Why This Change?
|
|
|
|
[Brief explanation of deprecation rationale]
|
|
|
|
**Benefits of Migration**:
|
|
- Benefit 1
|
|
- Benefit 2
|
|
|
|
---
|
|
|
|
## Migration Steps
|
|
|
|
### Step 1: [Action]
|
|
**What**: [Description]
|
|
|
|
**Before** (deprecated):
|
|
```
|
|
[Code example using old feature]
|
|
```
|
|
|
|
**After** (recommended):
|
|
```
|
|
[Code example using alternative]
|
|
```
|
|
|
|
### Step 2: [Action]
|
|
[Repeat pattern for each migration step]
|
|
|
|
---
|
|
|
|
## Migration Checklist
|
|
|
|
- [ ] Update code to use alternative
|
|
- [ ] Update tests
|
|
- [ ] Update documentation
|
|
- [ ] Test in development
|
|
- [ ] Deploy to production
|
|
- [ ] Verify functionality
|
|
- [ ] Remove deprecated feature usage
|
|
|
|
---
|
|
|
|
## Common Migration Scenarios
|
|
|
|
### Scenario 1: [Use Case]
|
|
**Old Approach**:
|
|
```
|
|
[Code]
|
|
```
|
|
|
|
**New Approach**:
|
|
```
|
|
[Code]
|
|
```
|
|
|
|
[Repeat for common scenarios]
|
|
|
|
---
|
|
|
|
## Troubleshooting
|
|
|
|
### Issue 1: [Common Problem]
|
|
**Symptom**: [What users see]
|
|
**Solution**: [How to fix]
|
|
|
|
[Repeat for common issues]
|
|
|
|
---
|
|
|
|
## Support Resources
|
|
|
|
- Migration guide: [link]
|
|
- API documentation: [link]
|
|
- Support channel: [link]
|
|
- Example migration: [link to example code]
|
|
|
|
**Need Help?**
|
|
- Email: [support email]
|
|
- Slack: [support channel]
|
|
- Office hours: [time]
|
|
|
|
---
|
|
|
|
## Timeline
|
|
|
|
- **Now**: Feature deprecated, warnings active
|
|
- **[Date]**: Migration support ends
|
|
- **[Date]**: Feature removed from production
|
|
|
|
**Don't wait! Migrate today.**
|
|
```
|
|
|
|
Write to `$MIGRATION_GUIDE`.
|
|
|
|
---
|
|
|
|
### 5. Generate Tasks
|
|
|
|
```markdown
|
|
# Tasks: Deprecation ${DEPRECATE_NUM}
|
|
|
|
**Workflow**: Deprecate (Phased Sunset)
|
|
|
|
---
|
|
|
|
## Phase 1: Announcement Tasks
|
|
|
|
### T001: Add Deprecation Warnings
|
|
**Description**: Add warnings to deprecated feature code
|
|
**Files**: [list]
|
|
**Warning Message**: "This feature is deprecated. Migrate to [alternative]. See [migration guide link]."
|
|
|
|
### T002: [P] Publish Migration Guide
|
|
**Description**: Publish migration guide
|
|
**Output**: ${MIGRATION_GUIDE}
|
|
**Parallel**: [P]
|
|
|
|
### T003: [P] Update Documentation
|
|
**Description**: Mark feature as deprecated in docs
|
|
**Files**: [doc files]
|
|
**Parallel**: [P]
|
|
|
|
### T004: [P] Announce Deprecation
|
|
**Description**: Communicate deprecation via all channels
|
|
**Channels**: Blog, email, in-app
|
|
**Parallel**: [P]
|
|
|
|
---
|
|
|
|
## Phase 2: Migration Support Tasks
|
|
|
|
### T005: Monitor Adoption
|
|
**Description**: Track usage of deprecated vs alternative
|
|
**Metrics**: [usage metrics]
|
|
**Frequency**: Weekly
|
|
**Duration**: [Phase 2 duration]
|
|
|
|
### T006: Provide User Support
|
|
**Description**: Help users migrate
|
|
**Activities**: Answer questions, resolve blockers
|
|
**Duration**: [Phase 2 duration]
|
|
|
|
### T007: Send Migration Reminders
|
|
**Description**: Remind users to migrate
|
|
**Schedule**: [reminder schedule]
|
|
**Content**: Progress update, deadline reminder
|
|
|
|
---
|
|
|
|
## Phase 3: Removal Tasks
|
|
|
|
### T008: Final Migration Check
|
|
**Description**: Verify ≥90% user migration
|
|
**Validation**: Usage metrics, stakeholder approval
|
|
|
|
### T009: Disable Feature
|
|
**Description**: Turn off deprecated feature in production
|
|
**Rollback Plan**: [how to re-enable if needed]
|
|
|
|
### T010: Remove Code
|
|
**Description**: Delete deprecated feature code
|
|
**Files**: [list all files to remove]
|
|
**Validation**: Tests still pass
|
|
|
|
### T011: [P] Cleanup Tests
|
|
**Description**: Remove tests for deprecated feature
|
|
**Files**: [test files]
|
|
**Parallel**: [P]
|
|
|
|
### T012: [P] Cleanup Documentation
|
|
**Description**: Remove deprecated feature from docs
|
|
**Files**: [doc files]
|
|
**Parallel**: [P]
|
|
|
|
### T013: Archive Artifacts
|
|
**Description**: Archive feature artifacts for historical reference
|
|
**Location**: [archive location]
|
|
|
|
---
|
|
|
|
## Summary
|
|
|
|
**Total Tasks**: 13
|
|
**Phase 1 (Announce)**: T001-T004 (4 tasks, [N] parallel)
|
|
**Phase 2 (Migrate)**: T005-T007 (3 tasks, ongoing)
|
|
**Phase 3 (Remove)**: T008-T013 (6 tasks, [N] parallel)
|
|
|
|
**Total Timeline**: [estimated timeline]
|
|
|
|
**Success Criteria**:
|
|
- ✅ Deprecation announced to all users
|
|
- ✅ Migration guide published
|
|
- ✅ ≥90% users migrated
|
|
- ✅ Feature removed safely
|
|
- ✅ Documentation updated
|
|
```
|
|
|
|
Write to `$TASKS_FILE`.
|
|
|
|
---
|
|
|
|
### 6. Execute Phased Deprecation
|
|
|
|
Execute across three phases:
|
|
|
|
```
|
|
📉 Executing Deprecation Workflow
|
|
|
|
Phase 1: Announcement (Month 1)
|
|
T001: Add Deprecation Warnings
|
|
✓ Warnings added to code
|
|
|
|
T002-T004: [Parallel] Publish Migration Guide, Update Docs, Announce
|
|
⚡ Executing 3 tasks in parallel...
|
|
✓ Migration guide published
|
|
✓ Documentation updated
|
|
✓ Deprecation announced
|
|
|
|
Phase 2: Migration Support (Months 2-3)
|
|
T005: Monitor Adoption
|
|
Week 1: 15% migrated
|
|
Week 2: 32% migrated
|
|
Week 4: 58% migrated
|
|
Week 6: 78% migrated
|
|
Week 8: 91% migrated ✅
|
|
|
|
T006: Provide User Support
|
|
✓ 12 support tickets resolved
|
|
✓ 3 migration blockers fixed
|
|
|
|
T007: Send Migration Reminders
|
|
✓ Weekly reminders sent
|
|
|
|
Phase 3: Removal (Month 4)
|
|
T008: Final Migration Check
|
|
✓ 91% users migrated
|
|
✓ Stakeholder approval received
|
|
|
|
T009: Disable Feature
|
|
✓ Feature disabled in production
|
|
✓ No issues reported
|
|
|
|
T010-T012: [Parallel] Remove Code, Cleanup Tests, Cleanup Docs
|
|
⚡ Executing 3 tasks in parallel...
|
|
✓ All cleanup tasks complete
|
|
|
|
T013: Archive Artifacts
|
|
✓ Artifacts archived
|
|
```
|
|
|
|
---
|
|
|
|
## Final Output
|
|
|
|
```
|
|
✅ Deprecation Workflow Complete - Deprecation ${DEPRECATE_NUM}
|
|
|
|
📊 Deprecation Results:
|
|
- Users migrated: 91% ✅
|
|
- Alternative adopted: 87% ✅
|
|
- Support tickets: 12 (all resolved) ✅
|
|
- Timeline: Completed on schedule ✅
|
|
|
|
📋 Artifacts:
|
|
- ${DEPRECATE_SPEC}
|
|
- ${MIGRATION_GUIDE}
|
|
- ${TASKS_FILE}
|
|
|
|
⏱️ Total Timeline: [duration]
|
|
|
|
✅ Feature Safely Removed:
|
|
- Code deleted and archived
|
|
- Documentation updated
|
|
- Users successfully migrated
|
|
|
|
📈 Next Steps:
|
|
- Monitor alternative feature adoption
|
|
- Archive learnings for future deprecations
|
|
```
|
|
|
|
---
|
|
|
|
## Operating Principles
|
|
|
|
1. **Phased Approach**: Announce → Migrate → Remove
|
|
2. **User-Centric**: Help users migrate successfully
|
|
3. **Communication**: Over-communicate timeline and alternatives
|
|
4. **Track Progress**: Monitor migration adoption
|
|
5. **Safe Removal**: Only remove when migration complete
|
|
|
|
---
|
|
|
|
## Success Criteria
|
|
|
|
✅ Deprecation announced to all affected users
|
|
✅ Migration guide published and accessible
|
|
✅ ≥90% user migration achieved
|
|
✅ Migration blockers resolved
|
|
✅ Feature removed safely
|
|
✅ Documentation and code cleanup complete
|
|
✅ Artifacts archived
|
|
|
|
---
|
|
|
|
**Workflow Coverage**: Addresses ~5% of development work (feature evolution)
|