🔧 Technical Documentation
Deployment
Version Management

Version Management

Complete guide to version management in the MyNATCA platform, including the VERSION file, semantic versioning, and version bumping workflows.

Overview

The MyNATCA platform uses a single source of truth approach for version management:

  • VERSION file - Canonical version number
  • package.json - Synchronized automatically
  • Git tags - Mark releases
  • Automated scripts - Handle version bumping

Version information is displayed on the platform landing page and used for release tracking.

VERSION File

Location and Format

platform/VERSION

Content:

1.0.1

Simple, single-line file containing the current version in semver format.

Why a VERSION File?

  • Single source of truth - One place to update version
  • Language agnostic - Not tied to npm/package.json
  • Easy automation - Simple to read/write in scripts
  • Clear intent - Explicit version declaration

Semantic Versioning

MyNATCA follows Semantic Versioning 2.0.0 (opens in a new tab):

MAJOR.MINOR.PATCH
  ↓     ↓     ↓
 1  .  0  .  1

MAJOR Version (1.0.0 → 2.0.0)

When to bump:

  • Breaking API changes
  • Incompatible database schema changes
  • Major feature rewrites
  • Removal of deprecated features
  • Changes requiring user migration

Examples:

  • Remove old API endpoints
  • Change authentication system
  • Restructure database schemas
  • Migrate to new framework

Communication required:

  • Announce breaking changes ahead of time
  • Provide migration guide
  • Document API changes
  • Update deployment procedures

MINOR Version (1.0.0 → 1.1.0)

When to bump:

  • New features (backwards compatible)
  • Enhancements to existing features
  • New API endpoints
  • New database tables (non-breaking)
  • Deprecation notices (but not removal)

Examples:

  • Add new report feature
  • Add new API endpoints
  • Enhance search functionality
  • Add new database columns (with defaults)

Communication required:

  • Announce new features
  • Update user documentation
  • Update API documentation

PATCH Version (1.0.0 → 1.0.1)

When to bump:

  • Bug fixes
  • Security patches
  • Performance improvements
  • Documentation updates
  • Dependency updates (minor)
  • Configuration changes

Examples:

  • Fix calculation error
  • Patch security vulnerability
  • Optimize query performance
  • Fix typos in documentation

Communication required:

  • Bug fix notes
  • Security advisory (if applicable)

Version Bumping Workflow

Recommended Method: npm Scripts

cd ~/dev/mynatca/platform
 
# Patch bump (most common)
npm run bump:patch   # 1.0.0 → 1.0.1
 
# Minor bump
npm run bump:minor   # 1.0.0 → 1.1.0
 
# Major bump
npm run bump:major   # 1.0.0 → 2.0.0
 
# Default (alias for bump:patch)
npm run bump

What Happens During Bump

The scripts/prepare-deployment.sh script runs:

Step 1: Prettier Format

npx prettier --write "**/*.{js,mjs,json,md,yaml,yml}"

Auto-formats all code files.

Step 2: ESLint Lint

npx eslint --fix "**/*.{js,mjs}"

Lints and auto-fixes code issues.

Step 3: TypeScript Check

npm run type-check

Validates TypeScript types (if applicable).

Step 4: Version Bump

node scripts/bump-version.js [patch|minor|major]

Updates VERSION and package.json files.

Step 5: Summary Shows what changed and next steps.

If any step fails, the entire process stops - version is not bumped unless all quality checks pass.

Manual Version Bump (Not Recommended)

If you need to bump version without quality checks:

cd ~/dev/mynatca/platform
 
# Direct script invocation
./scripts/bump-version.js patch   # 1.0.0 → 1.0.1
./scripts/bump-version.js minor   # 1.0.0 → 1.1.0
./scripts/bump-version.js major   # 1.0.0 → 2.0.0
 
# Or edit VERSION file manually
echo "1.0.2" > VERSION
 
# Then update package.json to match
npm version 1.0.2 --no-git-tag-version

Warning: Manual bumping skips quality checks. Always prefer npm run bump:* commands.

Version Bump Output

Successful Bump

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  MyNATCA Platform - Deployment Preparation
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Current version: 1.0.0
Bump type: patch

[1/4] Running Prettier format...
✓ Prettier format passed

[2/4] Running ESLint...
✓ ESLint passed

[3/4] Running TypeScript check...
✓ TypeScript check passed

[4/4] Bumping version...
✓ Version bumped

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✓ All checks passed! Ready for deployment
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Version: 1.0.0 → 1.0.1

Modified files:
  - VERSION
  - package.json
  - (any formatted/linted files)

Next steps:
  1. Review changes: git diff
  2. Stage files: git add .
  3. Commit: git commit -m "chore: bump version to 1.0.1"
  4. Tag: git tag v1.0.1
  5. Push: git push && git push --tags

Failed Bump

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  MyNATCA Platform - Deployment Preparation
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Current version: 1.0.0
Bump type: patch

[1/4] Running Prettier format...
✓ Prettier format passed

[2/4] Running ESLint...
✗ ESLint failed

Error: ESLint found errors that could not be auto-fixed
Fix these issues manually and try again

Action required: Fix the reported errors, then run bump again.

Committing Version Bumps

Standard Commit Process

After successful bump:

# 1. Review all changes
git diff
 
# 2. Stage all changes (code formatting + version bump)
git add .
 
# 3. Commit with version bump message
git commit -m "chore: bump version to 1.0.1"
 
# 4. Tag the release
git tag v1.0.1
 
# 5. Push to remote
git push origin feature/your-branch --tags

Commit Message Format

chore: bump version to X.Y.Z

Or with more detail:

chore: bump version to 1.1.0

New features:
- Add facility search
- Enhance member profile

Bug fixes:
- Fix date calculation
- Resolve authentication issue

Git Tagging

Creating Tags

Tags mark specific releases:

# Create annotated tag (recommended)
git tag -a v1.0.1 -m "Release 1.0.1: Bug fixes and improvements"
 
# Create lightweight tag
git tag v1.0.1
 
# Push tag to remote
git push origin v1.0.1
 
# Push all tags
git push --tags

Tag Naming Convention

Format: v{MAJOR}.{MINOR}.{PATCH}

Examples:

  • v1.0.0 - Major release
  • v1.1.0 - Minor release
  • v1.0.1 - Patch release
  • v2.0.0-beta.1 - Pre-release
  • v2.0.0-rc.1 - Release candidate

Listing Tags

# List all tags
git tag
 
# List tags with pattern
git tag -l "v1.0.*"
 
# List tags with annotations
git tag -n
 
# Show tag details
git show v1.0.1

Deleting Tags

# Delete local tag
git tag -d v1.0.1
 
# Delete remote tag
git push origin :refs/tags/v1.0.1
 
# Or use --delete
git push origin --delete v1.0.1

Version Display

Platform Landing Page

The current version is automatically displayed on the platform landing page:

URL: http://localhost:1300/ (development) or production URL

Location: Footer

Format: Version 1.0.1

Retrieving Version Programmatically

Read VERSION file:

const fs = require('fs');
const version = fs.readFileSync('VERSION', 'utf8').trim();
console.log(version); // "1.0.1"

From package.json:

const packageJson = require('./package.json');
console.log(packageJson.version); // "1.0.1"

From Git tag:

git describe --tags --abbrev=0
# v1.0.1

Version in Different Environments

Development

# VERSION file shows development version
cat VERSION
# 1.1.0-dev
 
# Or latest committed version
cat VERSION
# 1.0.1

Staging

# VERSION file shows staged version
cat VERSION
# 1.1.0-beta
 
# Or version from main/staging branch
cat VERSION
# 1.0.1

Production

# VERSION file shows production version
cat VERSION
# 1.0.1
 
# Matches latest git tag
git describe --tags --abbrev=0
# v1.0.1

Pre-Release Versions

For beta, RC, or development versions:

Beta Releases

# Manually set version
echo "1.1.0-beta.1" > VERSION
npm version 1.1.0-beta.1 --no-git-tag-version
 
# Tag
git tag v1.1.0-beta.1

Release Candidates

# Manually set version
echo "2.0.0-rc.1" > VERSION
npm version 2.0.0-rc.1 --no-git-tag-version
 
# Tag
git tag v2.0.0-rc.1

Development Versions

# Manually set version
echo "1.1.0-dev" > VERSION
npm version 1.1.0-dev --no-git-tag-version
 
# Don't tag development versions

Changelog Management

Update CHANGELOG.md

When bumping versions, update CHANGELOG.md:

# Changelog
 
All notable changes to this project will be documented in this file.
 
## [Unreleased]
 
## [1.0.1] - 2025-12-06
 
### Fixed
- Fix date calculation error in pay periods
- Resolve authentication timeout issue
 
### Changed
- Improve query performance for member search
- Update dependency versions
 
## [1.0.0] - 2025-12-01
 
### Added
- Initial production release
- Core member management
- Facility tracking
- Position grants

Format: Follow Keep a Changelog (opens in a new tab)

Categories:

  • Added - New features
  • Changed - Changes to existing functionality
  • Deprecated - Soon-to-be removed features
  • Removed - Removed features
  • Fixed - Bug fixes
  • Security - Security fixes

Release Process

Complete Release Workflow

# 1. Ensure you're on the right branch
git checkout staging  # or main for production
 
# 2. Pull latest changes
git pull origin staging
 
# 3. Run deployment preparation
npm run bump:minor  # or patch/major
 
# 4. Review changes
git diff
 
# 5. Stage files
git add .
 
# 6. Commit with version message
git commit -m "chore: bump version to 1.1.0
 
New features:
- Feature A
- Feature B
 
Bug fixes:
- Fix C
"
 
# 7. Tag the release
git tag -a v1.1.0 -m "Release 1.1.0: New features and bug fixes"
 
# 8. Push to remote
git push origin staging --tags
 
# 9. Create GitHub Release (optional)
# Go to GitHub → Releases → Draft a new release
# Select tag v1.1.0
# Add release notes
# Publish release
 
# 10. Deploy to staging/production
# (Automatic or manual deployment depending on setup)

Troubleshooting

Version Mismatch

Issue: VERSION and package.json don't match

Solution:

# Read version from VERSION file
VERSION=$(cat VERSION | tr -d '\n')
 
# Update package.json to match
npm version $VERSION --no-git-tag-version
 
# Verify match
cat VERSION
node -p "require('./package.json').version"

Bump Script Fails

Issue: npm run bump fails partway through

Solution:

# Check what failed
npm run bump:patch
 
# Fix reported issues manually
npx prettier --write "**/*.{js,mjs,json,md,yaml,yml}"
npx eslint --fix "**/*.{js,mjs}"
 
# Run bump again
npm run bump:patch

Tag Already Exists

Issue: Trying to create tag that already exists

Solution:

# Delete local tag
git tag -d v1.0.1
 
# Delete remote tag
git push origin --delete v1.0.1
 
# Create new tag
git tag v1.0.1
git push origin v1.0.1

Wrong Version Bumped

Issue: Bumped wrong version type (patch instead of minor)

Solution:

# If not yet committed
git checkout VERSION package.json
 
# Run correct bump
npm run bump:minor
 
# If already committed but not pushed
git reset HEAD~1
npm run bump:minor
git add .
git commit -m "chore: bump version to 1.1.0"
 
# If already pushed
# Create new commit with correct version
npm run bump:minor
git add .
git commit -m "chore: correct version to 1.1.0"
git push

Best Practices

DO ✅

  • Use npm run bump:* commands (includes quality checks)
  • Follow semantic versioning strictly
  • Update CHANGELOG.md with every release
  • Tag all releases with annotated tags
  • Test thoroughly before bumping version
  • Coordinate major version bumps with team
  • Document breaking changes clearly
  • Keep VERSION and package.json synchronized

DON'T ❌

  • Manually edit VERSION without updating package.json
  • Skip quality checks (using manual bump)
  • Forget to tag releases
  • Use arbitrary version numbers
  • Bump major version for minor changes
  • Skip CHANGELOG.md updates
  • Deploy without version bump
  • Create duplicate tags

Quick Reference

Commands

# Version bumping
npm run bump:patch   # 1.0.0 → 1.0.1 (bug fixes)
npm run bump:minor   # 1.0.0 → 1.1.0 (new features)
npm run bump:major   # 1.0.0 → 2.0.0 (breaking changes)
npm run bump         # Alias for bump:patch
 
# Manual bump (not recommended)
./scripts/bump-version.js patch
./scripts/bump-version.js minor
./scripts/bump-version.js major
 
# Check version
cat VERSION
node -p "require('./package.json').version"
git describe --tags --abbrev=0
 
# Tagging
git tag v1.0.1
git tag -a v1.0.1 -m "Release message"
git push origin v1.0.1
git push --tags

Files

  • VERSION - Single source of truth
  • package.json - Synchronized version
  • CHANGELOG.md - Release notes
  • scripts/bump-version.js - Bump script
  • scripts/prepare-deployment.sh - Full deployment prep

Related Documentation

Code Promotion WorkflowGit Hooks & Code Quality