Solution Versioning

Solutions use semantic versioning to track releases and enable controlled promotions through environments.

Why Version Solutions?

Release Management

Track what version is deployed where:

Solution	Development	Staging	Production
customer-portal	1.5.0	1.4.0	1.3.0
api-gateway	2.1.0	2.1.0	2.0.0

Promotion Control

Move specific versions through your pipeline:

Rollback Capability

Quickly revert to a known-good version:

Semantic Versioning

Version Format

MAJOR.MINOR.PATCH
  │     │     │
  │     │     └── Bug fixes, configuration tweaks
  │     └──────── New features, sequence updates
  └────────────── Breaking changes, major rewrites

Version Bump Guidelines

Change	Version Bump	Example
Fix configuration issue	Patch	1.0.0 → 1.0.1
Add new sequence	Minor	1.0.0 → 1.1.0
Update sequence version requirement	Minor	1.0.0 → 1.1.0
Add variable template	Minor	1.0.0 → 1.1.0
Remove sequence	Major	1.0.0 → 2.0.0
Remove variable	Major	1.0.0 → 2.0.0
Major architecture change	Major	1.0.0 → 2.0.0

Creating New Versions

In the UI

1. Navigate to the solution detail page
2. Click Add Version
3. Enter the new version number
4. Make your changes
5. Click Create Version

┌─────────────────────────────────────────────────────────┐
│  Add New Version                                        │
├─────────────────────────────────────────────────────────┤
│                                                         │
│  Version: [1.3.0                                ]       │
│                                                         │
│  Sequences:                                             │
│  ┌───────────────────────────────────────────────────┐  │
│  │ (sequence list)                                   │  │
│  └───────────────────────────────────────────────────┘  │
│                                                         │
│                      [Cancel]  [Create Version]         │
└─────────────────────────────────────────────────────────┘

Tip

To create a version pre-filled from an existing one, click New Version From This on any version row instead of Add Version.

Version Immutability

Note

Published solution versions are immutable — their sequence list, order, and version requirements cannot be edited. A version can still be deleted (unless it is the last remaining version).

What Cannot Change

• Sequence list
• Sequence order
• Sequence version requirements

What Can Change

• Creating new versions
• Environment-specific variable values

Version History

The solution detail page shows all versions:

┌─────────────────────────────────────────────────────────┐
│  Solution: customer-portal                              │
├─────────────────────────────────────────────────────────┤
│                                                         │
│  Versions:                                              │
│                                                         │
│  ┌─────────┬───────────────┬─────────────────────────┐  │
│  │ Version │ Created       │ Deployed To             │  │
│  ├─────────┼───────────────┼─────────────────────────┤  │
│  │ 1.5.0   │ Today         │ Development             │  │
│  │ 1.4.0   │ 3 days ago    │ Staging                 │  │
│  │ 1.3.0   │ 1 week ago    │ Production              │  │
│  │ 1.2.0   │ 2 weeks ago   │ -                       │  │
│  │ 1.1.0   │ 1 month ago   │ -                       │  │
│  │ 1.0.0   │ 2 months ago  │ -                       │  │
│  └─────────┴───────────────┴─────────────────────────┘  │
│                                                         │
│  [+ Add Version]                                        │
│                                                         │
└─────────────────────────────────────────────────────────┘

Environment State

Each environment tracks its current version:

┌─────────────────────────────────────────────────────────┐
│  Environment State: customer-portal                     │
├─────────────────────────────────────────────────────────┤
│                                                         │
│  ┌─────────────┬─────────┬─────────────┬────────────┐   │
│  │ Environment │ Version │ Deployed    │ By         │   │
│  ├─────────────┼─────────┼─────────────┼────────────┤   │
│  │ Development │ 1.5.0   │ 2 hours ago │ alice      │   │
│  │ Staging     │ 1.4.0   │ 3 days ago  │ bob        │   │
│  │ Production  │ 1.3.0   │ 1 week ago  │ admin      │   │
│  └─────────────┴─────────┴─────────────┴────────────┘   │
│                                                         │
│  [Deploy]  [Promote]  [Rollback]                        │
│                                                         │
└─────────────────────────────────────────────────────────┘

Deployment by Version

Deploy Specific Version

1. Navigate to solution
2. Select the version
3. Click Deploy
4. Choose target environment
5. Confirm

Promote Version

Move current version to next environment:

1. Navigate to environment state
2. Click Promote
3. Select target environment
4. Confirm

Best Practices

1. Meaningful Version Numbers

Don’t over-increment:

Good: 1.0.0 → 1.1.0 → 1.2.0 → 2.0.0
Bad:  1.0.0 → 2.0.0 → 3.0.0 → 4.0.0

2. Track Changes Externally

Mantis does not store per-version release notes, so keep a changelog in your source repository (or solution config-as-code) and use clear semantic version bumps:

v1.3.0: Added monitoring integration
v1.2.1: Fixed timeout in health check
v1.2.0: Updated to new database schema

3. Test Before Promoting

Validate each version in lower environments:

4. Version for Rollback

Keep at least one known-good version available:

Production: v1.3.0 (current)
Available for rollback: v1.2.0, v1.1.0

5. Coordinate Breaking Changes

Major versions may require:

• Variable updates in all environments
• Database migrations
• Coordination with other teams

Troubleshooting

Cannot Create Version

Cause: Version number already exists

Solution: Use a new, higher version number

Version Not Appearing

Cause: Version may not have been saved

Solution: Check for validation errors, re-save

Wrong Version Deployed

Cause: Selected wrong version in deployment

Solution: Deploy the correct version or rollback

Next Steps

• Creating Solutions - Create new solutions
• Variables - Configure variables
• Promotion Lifecycle - Environment progression
• Overview - Return to solutions overview