Skip to content

workflow-versioning.md

Latest commit

 

History

History
389 lines (284 loc) · 8.55 KB

workflow-versioning.md

File metadata and controls

389 lines (284 loc) · 8.55 KB

Workflow Versioning Guide

How to properly version n8n workflows using semantic versioning

Overview

Each workflow in this repository follows independent semantic versioning. This means:

  • Each workflow has its own version number
  • Versions follow the SemVer standard (MAJOR.MINOR.PATCH)
  • Version changes are documented in CHANGELOG.md
  • Breaking changes are clearly communicated

Semantic Versioning (SemVer)

Format

v MAJOR . MINOR . PATCH
  └─┬─┘   └─┬─┘   └─┬─┘
    │       │       └── Bug fixes, docs, non-breaking changes
    │       └────────── New features, backward compatible
    └────────────────── Breaking changes, incompatible updates

Version Components

MAJOR version when you make incompatible changes:

  • Change server configuration format
  • Remove or rename workflow nodes
  • Change required credentials
  • Modify data structure that workflows depend on
  • Remove features

MINOR version when you add functionality in a backward compatible manner:

  • Add new optional features
  • Add new configuration options (with defaults)
  • Improve existing functionality without breaking changes
  • Add new notification channels
  • Enhance error handling

PATCH version when you make backward compatible bug fixes:

  • Fix bugs
  • Update documentation
  • Improve error messages
  • Performance improvements
  • Security patches (non-breaking)

Version Examples

Portainer Upgrade Workflow

1.0.0 → 1.0.1  (PATCH)
- Fixed disk space check calculation
- Updated documentation
- Improved error messages

1.0.1 → 1.1.0  (MINOR)
- Added Slack notification support (in addition to email)
- Added pre-flight check for Docker socket access
- Added rollback capability (new feature, backward compatible)

1.1.0 → 2.0.0  (MAJOR)
- Changed server configuration from file to database
- Removed manual trigger, now schedule-only
- Requires n8n >= 2.0.0 (breaking dependency change)

When to Bump Versions

Immediately After Making Changes

Update version in TWO places:

1. Workflow JSON Metadata

{
  "name": "Portainer Upgrade Automation",
  "meta": {
    "templateVersion": "1.1.0",  // ← UPDATE THIS
    "lastUpdated": "2025-12-22",  // ← UPDATE THIS
    //... other metadata
  }
}

2. CHANGELOG.md

# Changelog - Portainer Upgrade Workflow

## [Unreleased]

## [1.1.0] - 2025-12-22  // ← ADD NEW VERSION

### Added
- Slack notification support in addition to email
- Pre-flight check for Docker socket access

### Changed
- Improved error handling in pre-flight checks

## [1.0.1] - 2025-12-21

### Fixed
- Disk space calculation was incorrect

Version Lifecycle

Development (Unreleased)

While developing in a feature branch:

// In workflow JSON
"meta": {
  "templateVersion": "1.1.0-dev",  // Use -dev suffix
  "lastUpdated": "2025-12-22"
}
# In CHANGELOG.md

## [Unreleased]

### Added
- New feature being developed

## [1.0.0] - 2025-12-21
...

Pre-release (Develop Branch)

When merged to develop for staging testing:

"meta": {
  "templateVersion": "1.1.0-beta",  // Use -beta suffix
  "lastUpdated": "2025-12-22"
}

Production (Main Branch)

When released to main:

"meta": {
  "templateVersion": "1.1.0",  // Remove suffix
  "lastUpdated": "2025-12-22"
}

Tag the release:

git tag -a portainer-upgrade-v1.1.0 -m "Release Portainer Upgrade v1.1.0"
git push --tags

CHANGELOG Format

Follow Keep a Changelog format:

# Changelog - {Workflow Name}

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

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this workflow adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

### Planned
- Features planned but not yet implemented

## [1.1.0] - 2025-12-22

### Added
- New features added

### Changed
- Changes to existing functionality

### Deprecated
- Features that will be removed in future

### Removed
- Features that were removed

### Fixed
- Bug fixes

### Security
- Security improvements

## [1.0.1] - 2025-12-21

### Fixed
- Bug fix description

## [1.0.0] - 2025-12-20

### Added
- Initial release
- Feature 1
- Feature 2
- Feature 3

[Unreleased]: https://github.com/spydisec/spydi-n8n-automation/compare/portainer-upgrade-v1.1.0...HEAD
[1.1.0]: https://github.com/spydisec/spydi-n8n-automation/compare/portainer-upgrade-v1.0.1...portainer-upgrade-v1.1.0
[1.0.1]: https://github.com/spydisec/spydi-n8n-automation/compare/portainer-upgrade-v1.0.0...portainer-upgrade-v1.0.1
[1.0.0]: https://github.com/spydisec/spydi-n8n-automation/releases/tag/portainer-upgrade-v1.0.0

Version Compatibility

Document compatibility requirements in metadata:

{
  "meta": {
    "templateVersion": "1.1.0",
    "n8nVersionMin": "1.15.0",
    "n8nVersionMax": "2.0.3",
    "compatibility": {
      "portainer": "portainer-ce:lts",
      "docker": ">= 20.10",
      "os": ["ubuntu-22.04", "debian-11", "centos-8"]
    },
    "dependencies": {
      "workflows": {
        "notification-router": ">=1.0.0"
      }
    }
  }
}

Breaking Changes

Communicating Breaking Changes

When making breaking changes (MAJOR version bump):

1. In CHANGELOG.md:

## [2.0.0] - 2025-12-25

### ⚠️ BREAKING CHANGES

- Server configuration format changed from JSON file to database table
- Migration guide: See docs/migration/1.x-to-2.x.md
- Old format no longer supported
- Requires manual intervention to upgrade

### Changed
- Refactored server configuration to use PostgreSQL

### Migration Required
See [Migration Guide](../../docs/migration/portainer-1.x-to-2.x.md) for upgrade steps.

2. In README.md:

## ⚠️ Version 2.0.0 Breaking Changes

If upgrading from v1.x.x:
- Server configuration format has changed
- Manual migration required
- See [Migration Guide](migration/1.x-to-2.x.md)
- Estimated migration time: 30 minutes

3. Create Migration Guide:

# Migration Guide: v1.x.x → v2.0.0

## What Changed
- Server configuration moved from servers.json to PostgreSQL

## Before You Begin
- Backup your current servers.json
- Ensure PostgreSQL is installed
- Estimated time: 30 minutes

## Step-by-Step Migration
1. Export current configuration...
2. Set up PostgreSQL database...
3. Import configuration...
4. Test new workflow...
5. Remove old servers.json...

## Rollback Procedure
If issues arise...

Version Validation

Our automation checks versions:

# Run version check
python scripts/check-version.py

# This validates:
# ✅ Version in JSON matches CHANGELOG
# ✅ Semantic versioning format
# ✅ CHANGELOG follows Keep a Changelog format
# ✅ Dates are valid
# ✅ Version progression is logical

Best Practices

DO

  • ✅ Update version immediately when making changes
  • ✅ Document all changes in CHANGELOG
  • ✅ Use semantic versioning strictly
  • ✅ Test version compatibility
  • ✅ Communicate breaking changes clearly
  • ✅ Provide migration guides for MAJOR changes
  • ✅ Tag releases in git

DON'T

  • ❌ Skip version numbers
  • ❌ Reuse version numbers
  • ❌ Make breaking changes in MINOR/PATCH versions
  • ❌ Forget to update CHANGELOG
  • ❌ Use dates as versions
  • ❌ Make multiple MAJOR changes in one version

Repository-Level Versioning

The repository itself also has versions:

# Repository CHANGELOG.md

## [1.2.0] - 2025-12-22

### Workflows Added
- Server Health Monitor v1.0.0
- MySQL Backup v1.0.0

### Workflows Updated
- Portainer Upgrade: v1.0.1 → v1.1.0

### Repository Changes
- Added DEVELOPMENT.md
- Improved CI/CD pipeline

Quick Reference

# 1. Make changes to workflow

# 2. Update version in workflow JSON
nano workflows/{category}/{workflow}/{workflow}.json
# Update meta.templateVersion and meta.lastUpdated

# 3. Update CHANGELOG
nano workflows/{category}/{workflow}/CHANGELOG.md
# Add new version entry with changes

# 4. Validate
python scripts/check-version.py

# 5. Commit
git add workflows/{category}/{workflow}/
git commit -m "feat: {workflow} v{new-version} - {description}"

# 6. After merge to main, tag release
git tag -a {workflow}-v{version} -m "Release {workflow} v{version}"
git push --tags

Questions?