---

name: app-versioning description: Guide to managing application versions and deployment releases.

App Versioning Skill

1. The Versioning Strategy

Simple Platform uses Semantic Versioning (SemVer): MAJOR.MINOR.PATCH (e.g., 1.0.0, 2.1.5).

• MAJOR: Breaking changes (e.g., changing a data type, removing a field).
• MINOR: New features (backward compatible) (e.g., new table, new field).
• Pre-Release: MAJOR.MINOR.PATCH-ENV.COUNTER (e.g., 1.1.0-dev.1, 1.1.0-staging.5).

2. Defining Version in SCL

The source of truth is apps/<app>/app.scl.

Copyid com.mycompany.crm
version 1.2.0  # <--- THIS LINE
display_name "CRM"

3. Deploying with Version Bumps

The CLI manages versions automatically based on the target environment (--env).

A. Starting a New Cycle (Prod -> Dev)

When you have a stable version (e.g., 1.0.0) and start new work, you MUST provide --bump.

Copy# Start work on next patch
simple deploy com.mycompany.crm --env dev --bump patch
# Result: 1.0.1-dev.1

B. Iterating (Dev -> Dev)

When iterating in a non-prod environment, the CLI auto-increments the counter. No flag needed.

Copysimple deploy com.mycompany.crm --env dev
# Result: 1.0.1-dev.2 -> 1.0.1-dev.3

C. Promoting (Dev -> Staging -> Prod)

Moving between environments handles the suffixes automatically.

Copy# Promote to Staging
simple deploy com.mycompany.crm --env staging
# Result: 1.0.1-staging.1

# Release to Prod
simple deploy com.mycompany.crm --env prod
# Result: 1.0.1 (Stable)

4. Best Practices

1. Always Forward: Versions must strictly increase. There is NO concept of rollback.
2. Forward Rollback: To revert a bad deployment, revert the code in git and deploy a new higher version.
3. Sync: Ensure app.scl is committed to git after a deployment, as the CLI updates it.