Versioning

Managing multiple graph versions for safe deployments and migrations.

Why Version Graphs?

Versioning allows you to:

• Deploy changes without breaking existing agents
• Test new features in beta before releasing
• Support multiple versions during migrations
• Rollback quickly if issues occur

Flutch uses semantic versioning: MAJOR.MINOR.PATCH

Semantic Versioning

MAJOR - Breaking changes (1.0.0 → 2.0.0)

• Changed input/output format
• Removed functionality
• Incompatible behavior changes

MINOR - New features, backwards-compatible (1.0.0 → 1.1.0)

• Added capabilities
• Improved features
• Optional new parameters

PATCH - Bug fixes, backwards-compatible (1.0.0 → 1.0.1)

• Bug fixes
• Performance improvements
• Security patches

Pre-release - Testing versions

• 2.0.0-beta - Beta version
• 2.0.0-rc.1 - Release candidate

Creating a New Version

1. Create Version Directory

TypeScript:

my-graph/
├── src/versions/
│   ├── v1.0.0/
│   │   └── builder.ts
│   └── v1.1.0/        # New version
│       └── builder.ts

Python:

my-graph/
├── graph/versions/
│   ├── v1_0_0/
│   │   └── builder.py
│   └── v1_1_0/        # New version
│       └── builder.py

2. Update Manifest

Add version to graph.manifest.json:

json
actions.copy
{
  "versioning": {
    "defaultVersion": "1.0.0",
    "supportedVersions": ["1.0.0", "1.1.0"]
  },
  "versions": {
    "1.0.0": {
      "status": "stable"
    },
    "1.1.0": {
      "status": "stable",
      "changelog": "Added multilingual support"
    }
  }
}

3. Deploy

bash
actions.copy
flutch graph deploy

Both versions now available. Agents on 1.0.0 continue working, new agents can use 1.1.0.

Multiple Versions

Stable + Beta

Test breaking changes before releasing:

json
actions.copy
{
  "versioning": {
    "defaultVersion": "1.0.0",
    "supportedVersions": ["1.0.0", "2.0.0-beta"]
  }
}

• 1.0.0 - Production agents
• 2.0.0-beta - Internal testing

Migration Support

Support old and new during migration period:

json
actions.copy
{
  "versioning": {
    "defaultVersion": "2.0.0",
    "supportedVersions": ["1.5.0", "2.0.0"]
  },
  "versions": {
    "1.5.0": {
      "status": "deprecated",
      "changelog": "Migrate to 2.0.0 by June 1st"
    }
  }
}

• New agents use 2.0.0
• Existing agents on 1.5.0 keep working
• Remove 1.5.0 after deadline

Deprecating Versions

Mark as Deprecated

json
actions.copy
{
  "versions": {
    "1.0.0": {
      "status": "deprecated",
      "changelog": "Migrate to 2.0.0 by June 1st"
    }
  }
}

Version still works, but marked for removal.

Remove Version

After grace period (3-6 months for MAJOR versions):

json
actions.copy
{
  "versioning": {
    "supportedVersions": ["2.0.0"]  // 1.0.0 removed
  }
}

Delete version directory:

bash
actions.copy
rm -rf src/versions/v1.0.0

Deploy:

bash
actions.copy
flutch graph deploy

Default Version

Agents use defaultVersion when version not specified:

json
actions.copy
{
  "versioning": {
    "defaultVersion": "1.0.0",
    "supportedVersions": ["1.0.0", "1.1.0"]
  }
}

Change Default

json
actions.copy
{
  "versioning": {
    "defaultVersion": "1.1.0"  // Changed
  }
}

Deploy:

bash
actions.copy
flutch graph deploy

New agents get 1.1.0. Existing agents unaffected.

Rollback

If new version has issues:

json
actions.copy
{
  "versioning": {
    "defaultVersion": "1.0.0"  // Back to old version
  }
}

Takes effect immediately after deploy.

Best Practices

1. Pin versions in production

javascript
actions.copy
// Good
const graph = "acme.support::1.0.0";

// Bad - changes with defaultVersion
const graph = "acme.support";

2. Grace period for MAJOR versions

• Keep old version 3-6 months
• Document breaking changes
• Provide migration guide

3. Test with beta versions

json
actions.copy
"supportedVersions": ["1.0.0", "2.0.0-beta"]

4. Document changes

json
actions.copy
{
  "versions": {
    "1.1.0": {
      "changelog": "Added French support, fixed date parsing"
    }
  }
}

5. Start with 1.0.0

• Not 0.1.0 (signals unstable)
• Use 1.0.0 for first production release