Productify

Appearance

Version Management ​

The ProductifyFW CLI provides comprehensive version management for your projects, integrating with CI/CD pipelines and application deployments.

Overview ​

Version management in the CLI:

  • Project Version: Stored in project.yaml, used in CI/CD for Docker image tagging
  • Application Version: Synced with backend applications, managed through copy/promote operations
  • Semantic Versioning: Full support for major.minor.patch versioning

Commands ​

pfy version show ​

Display the current project version from project.yaml.

bash
pfy version show
# Output: 1.2.3

pfy version set ​

Set the project version to a specific value.

bash
pfy version set --version 2.0.0
# Output: Version updated: 1.2.3 → 2.0.0

Flags:

  • --version: Version string in format major.minor.patch (required)

pfy version bump ​

Increment the project version using semantic versioning.

bash
# Increment patch version (1.2.3 → 1.2.4)
pfy version bump --part patch

# Increment minor version (1.2.3 → 1.3.0)
pfy version bump --part minor

# Increment major version (1.2.3 → 2.0.0)
pfy version bump --part major

Flags:

  • --part: Version part to increment: major, minor, or patch (default: patch)

Behavior:

  • Patch: Increments patch number, keeps major and minor
  • Minor: Increments minor number, resets patch to 0
  • Major: Increments major number, resets minor and patch to 0

Version in CI/CD ​

The project version from project.yaml is automatically used in CI/CD templates for Docker image tagging.

GitHub Actions ​

yaml
# Generated CI file includes version tag
tags: |
  ghcr.io/my-app:${{ github.sha }}
  ghcr.io/my-app:1.2.3         # From project.yaml
  ghcr.io/my-app:latest

GitLab CI ​

yaml
# GitLab CI builds with version tag
script:
  - docker build -t $IMAGE_NAME:$CI_COMMIT_SHA .
  - docker tag $IMAGE_NAME:$CI_COMMIT_SHA $IMAGE_NAME:1.2.3 # From project.yaml
  - docker push $IMAGE_NAME:1.2.3

Application Version Integration ​

When copying or promoting applications, the CLI can sync versions with the backend.

Promote with Version ​

bash
# Use version from project.yaml
pfy application promote \
  --application-id <id> \
  --target-tenant-id <tenant-id>

# Specify version explicitly
pfy application promote \
  --application-id <id> \
  --target-tenant-id <tenant-id> \
  --version 2.1.0

# Update project.yaml with promoted version (default: true)
pfy application promote \
  --application-id <id> \
  --target-tenant-id <tenant-id> \
  --version 2.1.0 \
  --update-version

Flags:

  • --version: Version to promote (defaults to project.yaml version)
  • --update-version: Update project.yaml with result (default: true)

Copy with Version ​

bash
# Copy using project.yaml version
pfy application copy \
  --source-application-id <id> \
  --target-tenant-id <tenant-id> \
  --slug new-app

# Specify version for copy
pfy application copy \
  --source-application-id <id> \
  --target-tenant-id <tenant-id> \
  --slug new-app \
  --version 1.5.0

# Update project.yaml after copy
pfy application copy \
  --source-application-id <id> \
  --target-tenant-id <tenant-id> \
  --slug new-app \
  --update-version

Flags:

  • --version: Version for copied application (defaults to project.yaml or source version)
  • --update-version: Update project.yaml with result (default: false)

Sync from Manager ​

Pull project configuration from the manager backend.

bash
pfy sync --project-id <project-id>

This command:

  1. Fetches project details from manager
  2. Updates project.yaml with project ID and name
  3. Preserves existing CI/CD settings

Use Case: Initialize local project.yaml from an existing manager project.

Workflows ​

Release Workflow ​

bash
# 1. Bump version for release
pfy version bump --part minor
# Version updated: 1.2.3 → 1.3.0

# 2. Generate updated CI/CD files
pfy ci update
# Creates workflows with version 1.3.0

# 3. Commit and tag
git add project.yaml .github/
git commit -m "Release v1.3.0"
git tag v1.3.0
git push origin main --tags

# 4. CI builds and pushes:
#    - my-app:abc123 (commit SHA)
#    - my-app:1.3.0 (version tag)
#    - my-app:latest

Environment Promotion ​

bash
# 1. Test in staging (tenant_staging)
pfy application create \
  --tenant-id tenant_staging \
  --slug my-app \
  --name "My App" \
  --version 1.2.3

# 2. After testing, promote to production
pfy version bump --part patch  # 1.2.3 → 1.2.4
pfy application promote \
  --application-id app_staging_123 \
  --target-tenant-id tenant_prod \
  --update-version

# project.yaml now has version 1.2.4
# Application in production has version 1.2.4

Multi-Environment Deployment ​

bash
# Update version in project.yaml
pfy version set --version 2.0.0

# Deploy to multiple environments
for env in dev staging prod; do
  pfy application promote \
    --application-id $APP_ID \
    --target-tenant-id tenant_${env} \
    --no-update-version  # Don't update project.yaml each time
done

Version Format ​

Versions must follow semantic versioning 2.0.0:

  • Format: major.minor.patch
  • Example: 1.2.3
  • Major: Breaking changes
  • Minor: New features, backwards compatible
  • Patch: Bug fixes, backwards compatible

Invalid versions:

bash
pfy version set --version 1.2       # [NO] Missing patch
pfy version set --version v1.2.3    # [NO] No 'v' prefix
pfy version set --version 1.2.3-rc1 # [NO] No pre-release tags

Valid versions:

bash
pfy version set --version 0.1.0     # [OK] Initial development
pfy version set --version 1.0.0     # [OK] First stable
pfy version set --version 2.15.7    # [OK] Any valid semver

Configuration ​

Version is stored in project.yaml:

yaml
project_name: my-app
version: 1.2.3 # ← Project version
ci:
  type: github
  language: go
  registry: ghcr.io
  image_name: my-app

Best Practices ​

1. Bump Before Release ​

Always increment version before creating a release:

bash
pfy version bump --part minor
git commit -am "Bump version to $(pfy version show)"
git tag "v$(pfy version show)"
git push --tags

2. Match Git Tags ​

Keep git tags in sync with project version:

bash
# Good: tag matches version
pfy version show  # 1.2.3
git tag v1.2.3

# Bad: tag doesn't match
pfy version show  # 1.2.3
git tag v1.2.4    # Mismatch!

3. Automate in CI ​

Add version bumping to your CI pipeline:

yaml
# .github/workflows/release.yml
- name: Bump version
  run: |
    pfy version bump --part patch
    git config user.name "CI Bot"
    git config user.email "ci@example.com"
    git commit -am "Bump version [skip ci]"
    git push

4. Environment-Specific Versions ​

Use different versions for different environments:

yaml
# project.yaml
version: 1.2.3 # Production version

environments:
  staging:
    version: 1.3.0-staging # Not supported yet, use description
    description: "Staging with version 1.3.0"
  production:
    version: 1.2.3
    description: "Production stable"

Troubleshooting ​

Version not updating in CI ​

Regenerate CI templates after version bump:

bash
pfy version bump --part minor
pfy ci update  # Regenerate with new version

Version mismatch between project.yaml and application ​

Sync application version:

bash
# Get current project version
VERSION=$(pfy version show)

# Update application
pfy application update-version \
  --application-id <id> \
  --version $VERSION

Lost version after git operations ​

Always commit project.yaml changes:

bash
git add project.yaml
git commit -m "Update version to $(pfy version show)"

See Also ​