Version Management

1.0.0 → 1.0.1  (patch fix)
1.0.0 → 1.1.0  (new tool added, backwards compatible)
1.0.0 → 2.0.0  (renamed tools, API changed)

# Create your plugin
noorle plugin new my-plugin

# Build
noorle plugin build

# Upload
noorle plugin push

# Creates v1 as active version

# Add new tools to src/
# pub fn new_tool() { ... }

# Increment MINOR version in package metadata
# In noorle.yaml, Cargo.toml, package.json, etc.

# Build
noorle plugin build

# Upload
noorle plugin push

# Creates v2 (backwards compatible, new features)

# Fix bugs in existing tools
# Behavior change only, no API changes

# Build
noorle plugin build

# Upload
noorle plugin push

# Creates v3 (backwards compatible, fixes only)

# Significant API changes:
# - Rename tools
# - Change parameter names/types
# - Remove deprecated tools
# - Change return types

# Update version
# e.g., 1.2.0 → 2.0.0

# Build and upload
noorle plugin build
noorle plugin push

# Creates v4 (breaking change)
# Previous versions still available

# View active version
noorle plugin info my-plugin --json | jq '.active_version'
# Output: 3

# See all versions
noorle plugin versions my-plugin

# Output:
# Version 1: archived (0 agents)
# Version 2: archived (2 agents)
# Version 3: active (15 agents)

# Make v2 active
noorle plugin activate my-plugin --version 2

# All new agents use v2
# Existing agents on v3 continue until updated

# Issue detected in v3
# Quickly switch to v2

noorle plugin activate my-plugin --version 2

# Agents now use v2
# Users can manually update to v3 when fixed

# Check which agents use each version
noorle agent list --filter 'plugin:my-plugin'

# Output:
# agent-prod:     my-plugin v3
# agent-staging:  my-plugin v3
# agent-legacy:   my-plugin v2

# Rollback staging agent only
noorle agent update agent-staging --plugin-version 2

# Production stays on v3 for monitoring

# Create staging environment
noorle agent create agent-staging \
  --plugin-id my-plugin \
  --plugin-version 3

# Create production environment
noorle agent create agent-prod \
  --plugin-id my-plugin \
  --plugin-version 2

# Test v3 in staging
# If successful, upgrade production
# If problems, keep production on v2

// ✅ Compatible: Add optional parameter
pub fn process(input: String, options: Option<String>) -> String {
    // Old code still works (None case)
    // New code uses options
}

// ✅ Compatible: Return new field in object
pub fn get_data(id: String) -> {
    "id": "...",
    "data": "...",
    "new_field": "..."  // New field added
}

// ❌ Breaking: Change required parameter
// pub fn process(input: String, options: String) -> String { }
// Old code breaks

// ❌ Breaking: Remove field from response
// pub fn get_data(id: String) -> {
//     "id": "...",
//     // "data" field removed
// }
// Parsing breaks

/// Process data with legacy algorithm.
///
/// ⚠️ **Deprecated in v2.0**
/// Use `process_v2()` instead.
/// Will be removed in v3.0 (2024-12-31)
pub fn process(input: String) -> String {
    log_warning("process() is deprecated, use process_v2()");
    process_v2(input)  // Delegate to new impl
}

pub fn process_v2(input: String) -> String {
    // New implementation
}

noorle plugin docs my-plugin --section migration

# Output documentation about:
# - What changed between versions
# - How to migrate code
# - Deprecation timeline

# Cargo.toml (Rust)
[dependencies]
serde = "=1.0.195"      # Exact version
reqwest = "~0.11.24"    # Patch updates only
uuid = "^1.6.1"         # Minor/patch updates

# OR package.json (TypeScript)
{
  "dependencies": {
    "axios": "1.6.0",
    "lodash-es": "~4.17.21",
    "uuid": "^9.0.0"
  }
}

# For patch releases (v1.0.0 → v1.0.1)
cargo update -p serde --precise 1.0.196

# For minor/major (v1.0.0 → v1.1.0)
cargo update

# For pinned versions
cargo add serde=1.0.200

# Check for vulnerabilities
cargo audit

# Output:
# Vulnerability: serde 1.0.190
# - Update to 1.0.200 or higher

# Update
cargo update -p serde --precise 1.0.200

# Create patch release
noorle plugin push
# Creates v3.1 (bug fix/security patch)

# Declare v2 as LTS with 12-month support
noorle plugin lts my-plugin --version 2 \
  --support-until "2025-03-22" \
  --security-fixes-only

# v2 receives critical fixes only
# Users encouraged to migrate to v3

noorle plugin deprecate my-plugin --version 1 \
  --sunset-date "2024-12-31" \
  --replacement-version 3

# Announcement:
# "v1 will be retired on 2024-12-31
#  Upgrade to v3 before then
#  v2 available as intermediate step"

noorle plugin retire my-plugin --version 1

# v1 no longer available
# Agents on v1 must update to v2+ before next invocation

# Main development branch
git checkout main

# Create release branch
git checkout -b v1.2.x
# Fixes go here

# Create maintenance branch
git checkout -b v1.x-maintenance
# Critical security fixes for v1

# Upload from appropriate branch
git checkout v1.2.x
noorle plugin push  # Creates v2 (1.2.x release)

# Fix bug in main
git commit -m "Fix parsing bug"

# Back-port to v1 maintenance
git checkout v1.x-maintenance
git cherry-pick <commit-hash>
git push

# Build and release v1.1.1
noorle plugin push

noorle plugin metrics my-plugin

# Output:
# v3 (current): 234ms avg, 0.02% errors, 1250 calls/day
# v2:           240ms avg, 0.05% errors,  220 calls/day
# v1:            N/A (retired)

# v3 healthier than v2 → Safe to keep active

noorle plugin adoption my-plugin --days 30

# Output:
# v3: 90% agents (2 weeks old)
# v2: 10% agents (legacy)

# Good adoption rate for new version

# Plugin Versioning Policy

## Semantic Versioning
We use MAJOR.MINOR.PATCH

## Release Cadence
- Patch releases: As needed (bug fixes)
- Minor releases: Monthly (new features)
- Major releases: Quarterly (breaking changes)

## Support Timeline
- Latest version: Full support
- Previous version: Bug/security fixes for 3 months
- Older versions: Security fixes only for 6 months

## Deprecation
- 6 weeks notice before removal
- Migration guide provided
- Previous version available for rollback

## Breaking Changes
- Avoid when possible
- Provide migration path
- Maintain support for previous version