Skip to content

Version Naming Guidelines

Overview

This document outlines the version naming conventions for Story Desk application. All versions should be updated in both package.json and configProvider.mjs to maintain consistency.

Semantic Versioning (SemVer)

We follow semantic versioning format: MAJOR.MINOR.PATCH

Version Components

MAJOR (X.0.0)

Increment when making incompatible API changes or major feature overhauls: - Breaking changes to existing functionality - Major architecture changes - Removal of deprecated features - Database schema changes requiring migration

Examples: - 1.0.0 → 2.0.0: Complete UI redesign - 1.5.2 → 2.0.0: New authentication system breaking existing sessions

MINOR (0.X.0)

Increment when adding functionality in a backward-compatible manner: - New features or components - New API endpoints - Performance improvements - Non-breaking UI enhancements

Examples: - 1.0.0 → 1.1.0: Added dark mode toggle - 1.2.5 → 1.3.0: New export functionality

PATCH (0.0.X)

Increment when making backward-compatible bug fixes: - Bug fixes - Security patches - Performance optimizations - Documentation updates - Minor UI tweaks

Examples: - 1.0.0 → 1.0.1: Fixed authentication bug - 1.2.1 → 1.2.2: Updated dependencies for security

Version Update Process

1. Manual Version Updates

Update version in ConfigProvider only: - configProvider.mjs - Line 16: static STORY_DESK_VERSION = "X.Y.Z"

Note: package.json version remains unchanged - all app versioning uses ConfigProvider constant.

2. Pre-commit Hook Protection

Our Lefthook configuration includes a version check that: - ✅ Allows commits when version is updated - ⚠️ Prompts confirmation when no version change detected - ❌ Blocks commits if confirmation not provided

3. Release Planning

Before incrementing versions, consider: - What type of changes are included? (Major/Minor/Patch) - Are there breaking changes? (Requires major bump) - Is this a hotfix? (Patch increment only) - Multiple features bundled? (Minor increment)

Examples

Feature Development Cycle

1.0.0 → 1.1.0 (Added user profiles)
1.1.0 → 1.1.1 (Fixed profile avatar bug)
1.1.1 → 1.2.0 (Added export functionality)
1.2.0 → 2.0.0 (New authentication system)

Hotfix Cycle

1.2.0 (Production)
    ↓
1.2.1 (Critical bug fix)
    ↓
1.2.2 (Security patch)

Pre-release Versions

For beta/alpha releases, append identifier: - 1.0.0-alpha.1 - Alpha release - 1.0.0-beta.1 - Beta release - 1.0.0-rc.1 - Release candidate

Best Practices

✅ Do

  • Update configProvider.mjs version for all releases
  • Use meaningful commit messages when bumping versions
  • Test thoroughly before version bumps
  • Document breaking changes in MAJOR updates

❌ Don't

  • Skip version updates for user-facing changes
  • Use arbitrary version numbers
  • Mix feature and bug fix changes in patch updates
  • Touch package.json version (leave at 0.1.0)

Version History Reference

Current version location: - ConfigProvider: STORY_DESK_VERSION constant (line 16) - package.json: Fixed at 0.1.0 (not used for app versioning)

Tools

  • Lefthook: Pre-commit version validation for configProvider.mjs
  • Git hooks: Automated ConfigProvider version consistency checks