Versioning

Proper versioning is essential for module management, upgrades, and compatibility. This guide covers versioning strategies for TinySystems modules.

Semantic Versioning

TinySystems modules follow Semantic Versioning (SemVer):

MAJOR.MINOR.PATCH

Component	When to Increment	Example
MAJOR	Breaking changes	Port schema changes, removed components
MINOR	New features (backward compatible)	New components, new ports
PATCH	Bug fixes (backward compatible)	Performance improvements, bug fixes

Examples

1.0.0 → 1.0.1  # Bug fix
1.0.1 → 1.1.0  # New component added
1.1.0 → 2.0.0  # Breaking schema change

Version Locations

Go Module

// go.mod
module github.com/myorg/my-module

go 1.21

For major versions ≥2:

// go.mod
module github.com/myorg/my-module/v2

go 1.21

Chart.yaml

yaml

apiVersion: v2
name: my-module
version: 1.2.3        # Chart version
appVersion: "1.2.3"   # Module version

Code Variables

// version.go
package main

var (
    Version   = "dev"
    Commit    = "unknown"
    BuildDate = "unknown"
)

Set at build time:

bash

go build -ldflags="-X main.Version=1.2.3 -X main.Commit=$(git rev-parse HEAD)"

Git Workflow

Tagging Releases

bash

# Create annotated tag
git tag -a v1.2.3 -m "Release v1.2.3: Description of changes"

# Push tag
git push origin v1.2.3

# Push all tags
git push origin --tags

Release Branches

main           ← development
  └── release/1.x  ← stable 1.x releases
      └── v1.0.0
      └── v1.1.0
      └── v1.2.0
  └── release/2.x  ← stable 2.x releases
      └── v2.0.0

Hotfix Workflow

bash

# Branch from release
git checkout -b hotfix/1.2.4 release/1.x

# Fix and commit
git commit -m "Fix critical bug"

# Tag and push
git tag -a v1.2.4 -m "Hotfix: Description"
git push origin v1.2.4

# Merge back to main if applicable
git checkout main
git merge hotfix/1.2.4

Breaking Changes

What Constitutes a Breaking Change

Change	Breaking?	Version Bump
Rename component	Yes	MAJOR
Remove port	Yes	MAJOR
Change port schema (incompatible)	Yes	MAJOR
Add required settings field	Yes	MAJOR
Add optional settings field	No	MINOR
Add new component	No	MINOR
Add new port	No	MINOR
Fix bug	No	PATCH
Performance improvement	No	PATCH

Handling Breaking Changes

Deprecation Period

// component.go
func (c *Component) GetInfo() module.Info {
    return module.Info{
        Name:        "legacy-transformer",
        Description: "DEPRECATED: Use transformer-v2 instead. Will be removed in v3.0.0",
        Tags:        []string{"deprecated"},
    }
}

Migration Guide

markdown

# Migrating to v2.0.0

## Breaking Changes

### Port Schema Changes

The `input` port schema changed from:
```json
{"data": "string"}

to:

json

{"payload": {"data": "string", "metadata": {}}}

Migration Steps

Update node edges to use new schema
Modify expression templates
Test with new version


3. **Parallel Support**

Run both versions simultaneously:

```yaml
# Deploy v1 and v2
apiVersion: operator.tinysystems.io/v1alpha1
kind: TinyModule
metadata:
  name: my-module-v1
spec:
  image: ghcr.io/myorg/my-module:v1.2.3
---
apiVersion: operator.tinysystems.io/v1alpha1
kind: TinyModule
metadata:
  name: my-module-v2
spec:
  image: ghcr.io/myorg/my-module:v2.0.0

Pre-release Versions

Alpha Releases

1.0.0-alpha.1
1.0.0-alpha.2

Early testing
API may change significantly
Not for production

Beta Releases

1.0.0-beta.1
1.0.0-beta.2

Feature complete
API mostly stable
Testing in staging environments

Release Candidates

1.0.0-rc.1
1.0.0-rc.2

Ready for release
Final testing
No new features

Ordering

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

Version in TinyNode

Specifying Version

yaml

apiVersion: operator.tinysystems.io/v1alpha1
kind: TinyNode
metadata:
  name: my-processor
spec:
  component: github.com/myorg/my-module/processor
  module: my-module-v1  # References specific version

Version in Module Name

yaml

# TinyModule with version in name
apiVersion: operator.tinysystems.io/v1alpha1
kind: TinyModule
metadata:
  name: http-module-v2
  namespace: tinysystems
spec:
  image: ghcr.io/tiny-systems/http-module:v2.0.0

Changelog

Format

markdown

# Changelog

## [Unreleased]

### Added
- New feature description

### Changed
- Changed behavior description

### Deprecated
- Deprecated feature description

### Removed
- Removed feature description

### Fixed
- Bug fix description

### Security
- Security fix description

## [1.2.0] - 2024-01-15

### Added
- New transformer component
- Support for JSON output

### Fixed
- Memory leak in filter component

Automated Changelog

yaml

# .github/release.yml
changelog:
  categories:
    - title: Breaking Changes
      labels:
        - breaking
    - title: Features
      labels:
        - enhancement
    - title: Bug Fixes
      labels:
        - bug
    - title: Documentation
      labels:
        - documentation

Automation

GitHub Actions Release

yaml

name: Release

on:
  push:
    tags:
      - 'v*'

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

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

      - name: Generate changelog
        id: changelog
        uses: mikepenz/release-changelog-builder-action@v4
        with:
          configuration: ".github/changelog-config.json"
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

      - name: Create release
        uses: softprops/action-gh-release@v1
        with:
          body: ${{ steps.changelog.outputs.changelog }}
          draft: false
          prerelease: ${{ contains(github.ref, 'alpha') || contains(github.ref, 'beta') || contains(github.ref, 'rc') }}

Version Bump Script

bash

#!/bin/bash
# scripts/bump-version.sh

VERSION=$1
if [ -z "$VERSION" ]; then
    echo "Usage: ./bump-version.sh <version>"
    exit 1
fi

# Update Chart.yaml
sed -i "s/^version:.*/version: $VERSION/" charts/my-module/Chart.yaml
sed -i "s/^appVersion:.*/appVersion: \"$VERSION\"/" charts/my-module/Chart.yaml

# Commit
git add charts/my-module/Chart.yaml
git commit -m "Bump version to $VERSION"

# Tag
git tag -a "v$VERSION" -m "Release v$VERSION"

echo "Version bumped to $VERSION"
echo "Run 'git push origin v$VERSION' to publish"

Dependency Versioning

Go Module Dependencies

// go.mod
require (
    github.com/tiny-systems/module v0.5.0
    github.com/tiny-systems/platform-api v0.4.0
)

Updating Dependencies

bash

# Update specific dependency
go get github.com/tiny-systems/module@v0.6.0

# Update all
go get -u ./...

# Tidy
go mod tidy

Helm Dependencies

yaml

# Chart.yaml
dependencies:
  - name: common
    version: "1.x.x"
    repository: "oci://ghcr.io/myorg/charts"

Best Practices

1. Version Early and Often

Tag releases consistently
Don't wait too long between versions
Document every change

2. Never Reuse Tags

bash

# BAD - never do this
git tag -d v1.0.0
git push origin :refs/tags/v1.0.0
git tag v1.0.0
git push origin v1.0.0

3. Communicate Changes

Write clear release notes
Announce breaking changes early
Provide migration guides

4. Test Before Release

bash

# Pre-release checklist
make test
make lint
make build
helm lint ./charts/my-module

5. Support Multiple Versions

Maintain release branches for LTS
Backport critical fixes
Document supported versions

Version Compatibility Matrix

Module Version	SDK Version	K8s Version	Notes
2.x	0.5+	1.25+	Current
1.x	0.3-0.5	1.23+	Maintenance
0.x	0.1-0.3	1.22+	Deprecated

Next Steps

Building Modules - Build process
Registry Publishing - Publish to registries
Helm Charts - Package charts

Versioning ​

Semantic Versioning ​

Examples ​

Version Locations ​

Go Module ​

Chart.yaml ​

Code Variables ​

Git Workflow ​

Tagging Releases ​

Release Branches ​

Hotfix Workflow ​

Breaking Changes ​

What Constitutes a Breaking Change ​

Handling Breaking Changes ​

Migration Steps ​

Pre-release Versions ​

Alpha Releases ​

Beta Releases ​

Release Candidates ​

Ordering ​

Version in TinyNode ​

Specifying Version ​

Version in Module Name ​

Changelog ​

Format ​

Automated Changelog ​

Automation ​

GitHub Actions Release ​

Version Bump Script ​

Dependency Versioning ​

Go Module Dependencies ​

Updating Dependencies ​

Helm Dependencies ​

Best Practices ​

1. Version Early and Often ​

2. Never Reuse Tags ​

3. Communicate Changes ​

4. Test Before Release ​

5. Support Multiple Versions ​

Version Compatibility Matrix ​

Next Steps ​

Versioning

Semantic Versioning

Examples

Version Locations

Go Module

Chart.yaml

Code Variables

Git Workflow

Tagging Releases

Release Branches

Hotfix Workflow

Breaking Changes

What Constitutes a Breaking Change

Handling Breaking Changes

Migration Steps

Pre-release Versions

Alpha Releases

Beta Releases

Release Candidates

Ordering

Version in TinyNode

Specifying Version

Version in Module Name

Changelog

Format

Automated Changelog

Automation

GitHub Actions Release

Version Bump Script

Dependency Versioning

Go Module Dependencies

Updating Dependencies

Helm Dependencies

Best Practices

1. Version Early and Often

2. Never Reuse Tags

3. Communicate Changes

4. Test Before Release

5. Support Multiple Versions

Version Compatibility Matrix

Next Steps