Skip to content

VERSION_RESET.md

Latest commit

 

History

History
197 lines (144 loc) · 5.78 KB

VERSION_RESET.md

File metadata and controls

197 lines (144 loc) · 5.78 KB

Version Reset: v2.8.0 → v0.3.0

Date: October 28, 2025
Status: Active
Decision: Reset version numbering to better reflect project maturity

🤔 Why Reset the Version?

After reaching v2.8.0 in just 2 days of development, we realized our version numbering was inflated and didn't accurately reflect the plugin's maturity.

The Problem

  • ❌ v2.8.0 suggests stability - but we're still rapidly iterating
  • ❌ Fast version increments - v0.1 → v2.8 in 48 hours = unsustainable
  • ❌ Breaking changes expected - users deserve clear signals
  • ❌ Not battle-tested - no external teams using it yet

The Solution

Reset to v0.3.0 to honestly communicate:

  • ✅ This is beta software - expect breaking changes
  • ✅ v0.x signals "in development" - industry standard
  • ✅ v1.0 is a meaningful milestone - when truly stable
  • ✅ Clearer expectations - users know what they're getting

📊 Version Philosophy

v0.x (Beta) - Current Phase

Characteristics:

  • Active development and experimentation
  • Breaking changes are expected between minor versions
  • Feature additions and workflow refinements
  • Documentation evolves with the product
  • Used primarily by maintainers and early adopters

What to expect:

  • ⚠️ Folder structures may change (like 02-review removal)
  • ⚠️ Command workflows may be redesigned
  • ⚠️ Configuration formats may evolve
  • ✅ Migration guides provided for breaking changes
  • ✅ Rapid bug fixes and improvements

v1.0 (Stable) - Future Milestone

Criteria for v1.0:

  1. External adoption - Used by multiple teams beyond maintainers
  2. Stable workflow - No breaking changes for 6+ months
  3. Complete documentation - All features fully documented
  4. Battle-tested - Proven in production across different project types
  5. External contributors - Community involvement
  6. Integration maturity - Works with common toolchains (CI/CD, etc.)

Timeline: When ready, not rushed. Could be 3-12 months.

Post v1.0 (Mature)

  • Semantic versioning strictly followed
  • Breaking changes only in major versions
  • Long-term support for stable releases
  • Backward compatibility prioritized

🗺️ Roadmap to v1.0

Phase 1: Foundation (v0.1-v0.5) ← We are here (v0.3)

  • ✅ Core commands working
  • ✅ Basic workflow established
  • 🔄 Refining folder structure
  • 🔄 Adding essential features (auto-assignment, progress tracking)
  • 🔄 Fixing workflow pain points

Phase 2: Refinement (v0.6-v0.9)

  • Workflow stabilization (fewer breaking changes)
  • Team collaboration features
  • Advanced integrations (Jira, Linear, etc.)
  • Performance optimizations
  • Comprehensive testing

Phase 3: Maturity (v0.10-v0.99)

  • External beta testers
  • Real-world usage feedback
  • Documentation polish
  • Migration tools for older versions
  • Long-running stability period (6+ months)

Phase 4: v1.0 Release

  • Feature freeze and polish
  • Final breaking changes resolved
  • Commitment to semantic versioning
  • Long-term support announced

📋 What Changed in v0.3.0?

This version reset comes with significant improvements:

Breaking Changes

  1. Folder structure simplified:

    • Removed 02-review/ (review is a process, not a state)
    • Renumbered all subsequent folders

  2. Workflow separation:

    • /setup-prd now moves to Ready (not In-Progress)
    • /code-prd moves Ready → In-Progress on first run
    • Clear separation between setup and implementation

  3. Review behavior:

    • No longer moves files automatically
    • Updates metadata only
    • User explicitly runs /setup-prd when ready

New Features

  • Auto-assignment to current GitHub user
  • Progress tracking with checkpoints
  • Dependency validation before starting work

See CHANGELOG.md for complete details.

🔄 npm dist-tags Strategy

To help users choose the right version:

# Latest (current)
npm install -g claude-prd-workflow@latest  # → v0.3.0

# Legacy (for existing v2.x users)
npm install -g claude-prd-workflow@legacy  # → v2.8.0

dist-tags

  • latest → v0.3.0+ (active development)
  • legacy → v2.8.0 (frozen, security fixes only)

Users on v2.8.0 can stay there until they're ready to migrate. We'll provide security fixes for v2.8.0 for the next 3 months.

🤝 For Users

If you're on v2.8.0 or earlier

Option 1: Migrate to v0.3.0 (Recommended)

Option 2: Stay on v2.8.0

  • Run: npm install -g claude-prd-workflow@legacy
  • Security fixes until January 2026
  • No new features
  • Eventually must migrate

If you're new

Just install normally:

npm install -g claude-prd-workflow

You'll get v0.3.0 automatically.

💡 Lessons Learned

What went wrong with v2.8?

  1. Too excited about features - Bumped minor version for every feature
  2. No version policy - Didn't define what warrants a version bump
  3. Ignored project maturity - Version didn't match reality

What we're doing differently

  1. Slower version increments - Major features = minor bump
  2. Clear criteria for v1.0 - Won't rush to "stable"
  3. Honest about beta status - v0.x clearly signals work-in-progress
  4. Better communication - This document exists!

📞 Questions?

  • "Will there be more breaking changes?" - Yes, but we'll provide migration guides and clear documentation
  • "When will v1.0 be ready?" - When it's truly stable, not before. Quality > speed.
  • "Can I stay on v2.8?" - Yes, but v0.3+ is actively developed
  • "How do I migrate?" - See MIGRATION_v2_to_v0.md

Maintained by: Yassine Hamou-Tahra
Last Updated: 2025-10-28
Status: Active