Versioning Guide

This document explains how versioning works in ResponsiveKit and how to update versions properly.

Semantic Versioning

ResponsiveKit follows Semantic Versioning 2.0.0 (SemVer):

MAJOR.MINOR.PATCH[-PRERELEASE][+BUILD]

Version Format

• MAJOR (X.0.0): Breaking changes, incompatible API changes
• MINOR (0.X.0): New features, backward-compatible
• PATCH (0.0.X): Bug fixes, backward-compatible
• PRERELEASE (0.0.0-alpha.1): Pre-release versions
• BUILD (0.0.0+20130313): Build metadata (optional)

Examples

• 1.0.0 - First stable release
• 1.2.3 - Version 1, feature set 2, patch 3
• 2.0.0 - Major version with breaking changes
• 0.1.0-beta.1 - Beta release (current)
• 0.1.0-alpha.1 - Alpha release
• 1.0.0-rc.1 - Release candidate

Pre-release Versions

Alpha (α)

Early development, unstable, missing features.

0.1.0-alpha.1
0.1.0-alpha.2
0.1.0-alpha.3

When to use:

• Initial development
• Core features incomplete
• API may change significantly
• Not recommended for production

Beta (β)

Feature-complete, but may have bugs.

0.1.0-beta.1  (current)
0.1.0-beta.2
0.1.0-beta.3

When to use:

• All planned features implemented
• Testing and bug fixing phase
• API mostly stable
• Ready for user testing
• Not recommended for production

Release Candidate (rc)

Final testing before stable release.

1.0.0-rc.1
1.0.0-rc.2
1.0.0-rc.3

When to use:

• No known critical bugs
• Final testing phase
• Only critical bug fixes allowed
• Ready for production if no issues found

Version Lifecycle

Current Stage: Beta

0.1.0-beta.1 → 0.1.0-beta.2 → 0.1.0-rc.1 → 1.0.0

Typical Release Cycle

1. Alpha Phase (0.x.0-alpha.x)

   • Core development
   • Breaking changes allowed
   • Internal testing

2. Beta Phase (0.x.0-beta.x) ← We are here

   • Feature complete
   • Bug fixes and polish
   • User testing
   • Minor API changes allowed

3. Release Candidate (x.x.x-rc.x)

   • Final testing
   • Only critical fixes
   • Production-ready

4. Stable Release (x.x.x)

   • Production-ready
   • Follows SemVer strictly

How to Update Version

1. Manual Update

Edit package.json:

{
  "version": "0.1.0-beta.2"
}

2. Using npm version (Recommended)

# Patch release (0.1.0 → 0.1.1)
npm version patch

# Minor release (0.1.0 → 0.2.0)
npm version minor

# Major release (0.1.0 → 1.0.0)
npm version major

# Pre-release versions
npm version prerelease --preid=beta  # 0.1.0-beta.1 → 0.1.0-beta.2
npm version prerelease --preid=alpha # 0.1.0-alpha.1 → 0.1.0-alpha.2
npm version prerelease --preid=rc    # 1.0.0-rc.1 → 1.0.0-rc.2

# Specific pre-release
npm version 0.2.0-beta.1
npm version 1.0.0-rc.1
npm version 1.0.0

3. Version Bump Examples

From current beta to next beta:

npm version prerelease --preid=beta
# 0.1.0-beta.1 → 0.1.0-beta.2

From beta to release candidate:

npm version 0.1.0-rc.1
# 0.1.0-beta.2 → 0.1.0-rc.1

From rc to stable:

npm version 0.1.0
# 0.1.0-rc.1 → 0.1.0

From stable to next minor:

npm version minor
# 0.1.0 → 0.2.0

Version Update Checklist

Before updating version:

• All planned features implemented (for beta/rc)
• All tests passing
• Code formatted and linted (pnpm check:fix)
• Documentation updated
• CHANGELOG.md updated (if exists)
• Git working directory clean
• Review breaking changes (for major versions)

After updating version:

• Commit version change
• Create git tag: git tag v0.1.0-beta.2
• Push commits: git push
• Push tags: git push --tags
• Build extension: pnpm build
• Create release zip: pnpm zip
• Test extension in browser
• Create GitHub release (optional)

Version in Extension

The version in package.json is automatically used in the extension's manifest.json:

{
  "version": "0.1.0",
  "version_name": "0.1.0-beta.1"
}

• version: Numeric version (required by browsers)
• version_name: Display version (shows in browser)

WXT automatically handles this conversion.

Roadmap to 1.0.0

0.1.0-beta.x (Current)

• ✅ Core functionality working
• ✅ Toggle via extension icon
• ✅ Real-time breakpoint detection
• ✅ Animated info panel
• 🔄 User testing and feedback
• 🔄 Bug fixes

0.1.0-rc.x (Next)

• All beta bugs fixed
• Performance optimization
• Final UI polish
• Documentation complete
• Ready for production

1.0.0 (Stable)

• Production-ready
• No known critical bugs
• Full documentation
• User guide complete
• Published to Chrome/Firefox stores

Future Versions

• 1.1.0: New features (customizable position, keyboard shortcuts)
• 1.2.0: More features (screenshot capture, custom breakpoints)
• 2.0.0: Major redesign or breaking changes

Best Practices

DO ✅

• Follow SemVer strictly after 1.0.0
• Update version before creating releases
• Tag releases in git
• Document breaking changes
• Test thoroughly before version bump
• Keep version in sync with git tags

DON'T ❌

• Skip version numbers
• Use version 1.0.0 before production-ready
• Make breaking changes in patch versions
• Forget to update documentation
• Release without testing
• Use inconsistent version formats

Version History

Version	Date	Status	Notes
0.1.0-beta.1	2024-12-08	Current	Initial beta release

References

• Semantic Versioning 2.0.0
• npm version documentation
• Chrome Extension Versioning
• Firefox Extension Versioning