Skip to content

VERSION_IMPLEMENTATION_SUMMARY.md

Latest commit

 

History

History
228 lines (165 loc) · 5.81 KB

VERSION_IMPLEMENTATION_SUMMARY.md

File metadata and controls

228 lines (165 loc) · 5.81 KB

✅ Version Management - Implementation Complete

Summary of Changes

The version management system has been updated to support dry-run mode for local builds, preventing accidental commits of auto-generated versions.

What Changed

1. Enhanced setVersion.js

Added support for command-line flags:

# For local development (no file changes)
node setVersion.js --dry-run
node setVersion.js --local

# For CI/packaging (writes to disk)
node setVersion.js

# Show help
node setVersion.js --help

Key features:

  • --dry-run / -d: Calculate versions without writing
  • --local / -l: Alias for --dry-run
  • --help / -h: Show documentation
  • Clear visual indicators (🔍, ✅, ⏭️) for what's happening
  • Prevents package.json modifications in local dev

2. Added npm Scripts

In package.json:

{
  "scripts": {
    "version": "node setVersion.js",           // CI mode
    "version:local": "node setVersion.js --local",   // Local mode
    "version:check": "node setVersion.js --dry-run"  // Check only
  }
}

3. Created Documentation

New files:

  • VERSION_MANAGEMENT.md - Comprehensive guide on local vs CI builds
  • resetVersion.js - Utility to reset versions to base (cleanup script)

Updated files:

  • HOW_TO_RELEASE.md - Updated to mention --dry-run flag
  • setVersion.js - Added help documentation and flags

How Version Property Works

Source of Version

The version in package.json comes from two sources depending on context:

1. In Git (Source Control)

Static placeholder that matches base version from version.json:

// version.json
{
  "version": "0.1.0-preview.{height}"
}

// package.json (committed)
{
  "version": "0.1.0-preview.0"
}

2. During Build (CI/CD)

Dynamically calculated by setVersion.js based on git history:

// package.json (after setVersion.js runs)
{
  "version": "0.1.0-preview.127"
}

The {height} placeholder is replaced with actual commit count.

Answer to Your Question

"Where is this version property coming from?"

Answer:

  • In source code: Manually set placeholder version (0.1.0-preview.0)
  • During CI build: Calculated by setVersion.js using Nerdbank.GitVersioning
  • Based on: Git commit count + version.json configuration

"I only want this version to be set during build"

Solution Implemented: ✅ Local builds: Use --dry-run flag (no file modifications) ✅ CI builds: Run without flags (writes versions to disk for packaging) ✅ Source control: Keep placeholder versions only

Usage Guide

For Developers (Local Builds)

# Build your code
npm run build

# Check version (without modifying files)
npm run version:check

# Output: 📦 Calculated version: 0.1.0-preview.127
#         ⏭️  Skipped updating root package.json (dry-run mode)

# Your git status remains clean!

For CI/CD Pipeline

# Already configured in .github/workflows/ci.yml
- name: Build package
  run: npm run build

- name: Set version with Nerdbank.GitVersioning
  run: node setVersion.js  # No --dry-run flag!

- name: Run tests
  run: npm test

Key Benefits

Benefit Description
🧹 Clean Git No version changes in working directory
🔒 No Accidental Commits Dry-run mode prevents file modifications
📦 CI Packaging Versions written only during CI for npm pack
🎯 Clear Intent Explicit flags for different build contexts
📖 Self-Documenting Built-in help and clear output messages

Migration Checklist

  • Update setVersion.js with dry-run support
  • Add npm scripts for version commands
  • Create VERSION_MANAGEMENT.md documentation
  • Create resetVersion.js utility script
  • Update HOW_TO_RELEASE.md
  • Verify CI workflow uses correct mode
  • Reset all package.json to placeholder versions
  • Document in README or contributing guide
  • Communicate to team about new workflow

Next Steps

1. Reset Package Versions (One-Time)

Run this to set all packages back to base version:

node resetVersion.js

This will reset all package.json files to 0.1.0-preview.0 (or whatever's in version.json).

2. Test Locally

# Should show version without modifying files
npm run version:check

# Verify no changes
git status

3. Commit Changes

git add setVersion.js
git add resetVersion.js
git add package.json
git add VERSION_MANAGEMENT.md
git add HOW_TO_RELEASE.md
git commit -m "Add dry-run mode for version management

- Add --dry-run and --local flags to setVersion.js
- Add npm scripts: version:local and version:check
- Create VERSION_MANAGEMENT.md documentation
- Create resetVersion.js utility script
- Update HOW_TO_RELEASE.md with new workflow

This prevents package.json version changes during local builds
while maintaining automatic versioning in CI/CD pipeline."

4. Update Team

Share VERSION_MANAGEMENT.md with the team and highlight:

  • Always use npm run version:check or --dry-run locally
  • Never commit auto-generated versions
  • CI handles version writing automatically

Quick Reference

# ✅ CORRECT: Local development
npm run version:check
node setVersion.js --dry-run
node setVersion.js --local

# ❌ WRONG: Don't use this locally
node setVersion.js  # Will modify files!

# ✅ CORRECT: CI/CD only
node setVersion.js  # No flags

# 🛠️ UTILITY: Reset after accidental modification
node resetVersion.js

Status: ✅ Complete - Ready for Use
Documentation: See VERSION_MANAGEMENT.md for full guide
Date: November 4, 2025