Managing Release Versions

This workflow covers managing release versions, including semantic versioning, version pinning, blocklists, and version conflicts. Use this to control which versions are available to clients.

Prerequisites

• API credentials with release management permissions
• Understanding of semantic versioning
• Knowledge of version pinning and blocklist requirements

Understanding Semantic Versioning

Big Picture uses semantic versioning (SemVer) for releases:

Format: MAJOR.MINOR.PATCH[-PRERELEASE][+BUILD]

Examples:

• 1.0.0 — Production release
• 1.0.0-beta.1 — Beta pre-release
• 1.0.0-alpha.2 — Alpha pre-release
• 1.0.0+20240115.abc123 — Build metadata (optional)

Components:

• MAJOR — Incompatible API changes
• MINOR — Backward-compatible functionality additions
• PATCH — Backward-compatible bug fixes
• PRERELEASE — Optional identifier (alpha, beta, rc)
• BUILD — Optional build metadata (not used in comparison)

Step 1: Check Available Versions

List versions for a product:

curl "${BP_BASE_URL}/v1/products/prod_xyz789/releases?channel=stable" \
  -H "Authorization: Bearer $BP_API_TOKEN"

Response:

{
  "releases": [
    {
      "release_id": "rel_abc123",
      "version": "1.2.3",
      "channel": "stable",
      "published_at": "2024-01-15T10:30:00Z"
    },
    {
      "release_id": "rel_def456",
      "version": "1.2.2",
      "channel": "stable",
      "published_at": "2024-01-10T09:00:00Z"
    }
  ]
}

Step 2: Get Latest Version

Get the latest version for a channel:

curl "${BP_BASE_URL}/v1/products/prod_xyz789/releases/latest?channel=stable" \
  -H "Authorization: Bearer $BP_API_TOKEN"

Response:

{
  "release_id": "rel_abc123",
  "version": "1.2.3",
  "channel": "stable",
  "published_at": "2024-01-15T10:30:00Z"
}

Step 3: Configure Version Pinning

Pin to a specific version range using update policies:

curl -X PUT "${BP_BASE_URL}/v1/tenants/tenant_abc123/policies/prod_xyz789" \
  -H "Authorization: Bearer $BP_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "stable",
    "mode": "NOTIFY_ONLY",
    "pinned_range": ">=1.2.0,<2.0.0"
  }'

Pinning examples:

• "1.2.3" — Exact version pin
• ">=1.2.0,<2.0.0" — Version range pin (allow 1.x, block 2.x)
• ">=1.0.0,<2.0.0" — Major version pin (block major upgrades)

See Managing Update Policies for details.

Step 4: Add Version to Blocklist

Block a specific version:

curl -X POST "${BP_BASE_URL}/v1/tenants/tenant_abc123/blocklist" \
  -H "Authorization: Bearer $BP_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": "prod_xyz789",
    "blocked_version": "1.2.3",
    "reason": "CVE-2024-12345: Critical security vulnerability"
  }'

Response:

{
  "blocklist_id": "block_abc123",
  "tenant_id": "tenant_abc123",
  "product_id": "prod_xyz789",
  "blocked_version": "1.2.3",
  "reason": "CVE-2024-12345: Critical security vulnerability",
  "blocked_at": "2024-01-15T10:40:00Z"
}

Step 5: Remove Version from Blocklist

Remove a version from the blocklist:

curl -X DELETE "${BP_BASE_URL}/v1/tenants/tenant_abc123/blocklist/prod_xyz789/1.2.3" \
  -H "Authorization: Bearer $BP_API_TOKEN"

Step 6: Check Blocklist Status

Query blocklist entries:

curl "${BP_BASE_URL}/v1/tenants/tenant_abc123/blocklist?product_id=prod_xyz789" \
  -H "Authorization: Bearer $BP_API_TOKEN"

Response:

{
  "blocklist": [
    {
      "blocklist_id": "block_abc123",
      "product_id": "prod_xyz789",
      "blocked_version": "1.2.3",
      "reason": "CVE-2024-12345: Critical security vulnerability",
      "blocked_at": "2024-01-15T10:40:00Z"
    }
  ]
}

Version Conflicts

Duplicate Version

If you try to publish the same version twice:

Error:

{
  "error": "version_conflict",
  "message": "Version 1.2.3 already exists in channel stable",
  "existing_release_id": "rel_abc123"
}

Resolution: Use a different version or revoke the existing release first.

Version Downgrade

If you try to publish an older version:

Allow downgrade:

curl -X POST "${BP_BASE_URL}/v1/releases" \
  -H "Authorization: Bearer $BP_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": "prod_xyz789",
    "version": "1.2.2",
    "channel": "stable",
    "allow_version_downgrade": true,
    "artifacts": [...]
  }'

Note: Downgrades require explicit flag and are typically used for hotfixes.

Release Channels

Channels are independent version sequences:

• Same version on multiple channels — Allowed (channels are independent)
• Version progression per channel — Each channel maintains its own version sequence
• Channel-specific policies — Policies can be configured per channel

Default channels:

• stable — Production releases
• beta — Pre-release testing
• internal — Internal testing

Custom channels can be created as needed.

Version Validation

Before publishing, versions are validated:

1. SemVer format — Must be valid semantic version
2. Uniqueness — No duplicate version in same channel
3. Progression — Version must be newer than current (unless downgrade allowed)
4. Artifact integrity — Artifacts must have valid hashes

Best Practices

Use semantic versioning: Follow SemVer consistently across all products.

Promote through channels: Promote versions through channels: internal → beta → stable.

Document version changes: Include release notes explaining version changes.

Pin critical environments: Use version pinning for critical environments to prevent unexpected upgrades.

Maintain blocklists: Keep blocklists up to date with known problematic versions.

Test version validation: Test version validation in CI/CD before publishing.

Plan rollbacks: Always have a rollback plan before publishing new versions.

Next Steps

• Configure update policies — see Managing Update Policies
• Handle rollbacks — see Handling Rollbacks
• Create releases — see Creating a Release