Version Management

Version management ensures consistent, predictable releases and enables teams to communicate changes effectively. This practice defines how to version software artifacts in NUP projects.

Semantic Versioning (SemVer)

NUP follows Semantic Versioning 2.0.0 for all software releases.

Version Format

Standard Format

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

Examples:
1.0.0           Initial release
1.0.1           Patch release (bug fix)
1.1.0           Minor release (new feature)
2.0.0           Major release (breaking changes)
1.0.0-alpha.1   Alpha pre-release
1.0.0-beta.2    Beta pre-release
1.0.0-rc.1      Release candidate
1.0.0+build.123 With build metadata

Version Components

Pre-Release Versions

Pre-Release Identifiers

Pre-Release Precedence

1.0.0-alpha.1 < 1.0.0-alpha.2 < 1.0.0-beta.1 < 1.0.0-rc.1 < 1.0.0

Build Metadata

Build metadata is appended with a + sign and does not affect version precedence.

Common Build Metadata

1.0.0+build.123         CI build number
1.0.0+20240115          Date-based build
1.0.0+sha.a1b2c3d       Git commit SHA
1.0.0-beta.1+build.456  Pre-release with build

Using Git SHA for Build Numbers

# Get short Git SHA
VERSION="1.0.0+sha.$(git rev-parse --short HEAD)"
echo $VERSION  # 1.0.0+sha.a1b2c3d

Implementation by Language

JavaScript/TypeScript (package.json)

{
  "name": "my-app",
  "version": "1.2.3",
  "scripts": {
    "version:patch": "npm version patch",
    "version:minor": "npm version minor",
    "version:major": "npm version major"
  }
}

Python (pyproject.toml)

[project]
name = "my-app"
version = "1.2.3"

# Or use dynamic versioning
[tool.setuptools_scm]
write_to = "src/my_app/_version.py"

.NET (csproj)

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <Version>1.2.3</Version>
    <AssemblyVersion>1.2.3.0</AssemblyVersion>
    <FileVersion>1.2.3.0</FileVersion>
  </PropertyGroup>
</Project>

Go (version.go)

package version

var (
    Version   = "1.2.3"
    GitCommit = "unknown"
    BuildDate = "unknown"
)

Version Automation

Git Tags

# Create annotated tag
git tag -a v1.2.3 -m "Release version 1.2.3"

# Push tags
git push origin v1.2.3
git push --tags

Automated Versioning with CI

# GitHub Actions example
name: Release

on:
  push:
    tags:
      - 'v*'

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Get version from tag
        id: version
        run: echo "VERSION=${GITHUB_REF#refs/tags/v}" >> $GITHUB_OUTPUT

      - name: Build with version
        run: |
          echo "Building version ${{ steps.version.outputs.VERSION }}"

Conventional Commits for Version Bumps

# Patch version (fix commits)
git commit -m "fix: correct calculation error"

# Minor version (feat commits)
git commit -m "feat: add new reporting feature"

# Major version (breaking changes)
git commit -m "feat!: redesign API endpoints"
# or
git commit -m "feat: change response format

BREAKING CHANGE: response structure has changed"

API Versioning

URL Path Versioning

GET /api/v1/users
GET /api/v2/users

Header Versioning

GET /api/users
Accept: application/vnd.myapp.v1+json

Query Parameter Versioning

GET /api/users?version=1

Versioning Strategy Recommendation

# Recommended: URL path versioning for public APIs
api:
  version: v1
  endpoints:
    - /api/v1/users
    - /api/v1/orders

# Internal: Use header versioning for flexibility
internal_api:
  version_header: "X-API-Version"
  default_version: "2024-01-15"

Database Schema Versioning

Migration Versioning

migrations/
├── V001__create_users_table.sql
├── V002__add_email_column.sql
├── V003__create_orders_table.sql
└── V004__add_user_preferences.sql

Tools for Schema Versioning

Version Display

Runtime Version Information

// Express.js health endpoint
app.get('/health', (req, res) => {
  res.json({
    status: 'healthy',
    version: process.env.APP_VERSION || '0.0.0',
    commit: process.env.GIT_COMMIT || 'unknown',
    buildDate: process.env.BUILD_DATE || 'unknown'
  });
});

Build-Time Version Injection

ARG VERSION=0.0.0
ARG GIT_COMMIT=unknown

ENV APP_VERSION=$VERSION
ENV GIT_COMMIT=$GIT_COMMIT

# Build command
# docker build --build-arg VERSION=1.2.3 --build-arg GIT_COMMIT=$(git rev-parse --short HEAD) .

Version Communication

Changelog Format

# Changelog

All notable changes to this project will be documented in this file.

## [Unreleased]

### Added
- New feature X

### Changed
- Updated dependency Y

## [1.2.0] - 2024-01-15

### Added
- User profile feature (#123)
- Export to CSV functionality (#456)

### Fixed
- Login timeout issue (#789)

### Security
- Updated vulnerable dependency (#101)

## [1.1.0] - 2024-01-01
...

Related Resources

• Branching Strategy - Git branching workflow
• Build & Integration - CI/CD versioning
• Guidelines - Development guidelines

Compliance

This section fulfills ISO 13485 requirements for product identification (7.5.3), traceability (7.5.3.2), and control of records (4.2.4), and ISO 27001 requirements for configuration management (A.8.9), change management (A.8.32), and asset management (A.5.9).

View full compliance matrix