Files

Achintha Isuru 085445e730 feat: add comprehensive release process documentation and version file references

- Introduced RELEASE_VISUAL_GUIDE.md for a visual overview of the release pipeline, including development, staging, and production phases.
- Created RELEASE_WORKFLOW.md detailing step-by-step release procedures for single and multi-product releases, including hotfix processes.
- Added VERSION_FILES_REFERENCE.md to outline all necessary version file updates for each product during releases, ensuring consistency and completeness.

2026-03-05 10:49:09 -05:00

9.3 KiB

Raw Blame History

Version File Locations Reference

When releasing a product, update version numbers in all applicable files. Use this checklist to ensure nothing is missed.

📱 Staff Mobile App Release

All files to update when releasing staff mobile app:

1. Pubspec.yaml

File: /apps/mobile/apps/staff_app/pubspec.yaml

# Current state (example)
version: 0.1.0+5

# Change to (example for v0.2.0)
version: 0.2.0+6

Rules:

Format: MAJOR.MINOR.PATCH+BUILD_NUMBER
Always increment BUILD_NUMBER
For each new version, start BUILD_NUMBER at +1

2. CodeMagic Configuration

File: /codemagic.yaml

Find the mobile-client-build workflow section:

workflows:
  mobile-client-build:
    name: Mobile Client Build
    
    environment:
      # ... other env vars ...
      groups:
        - default
        - mobile-staff-build  # ← This group might have version
      
    on_success:
      - |
        VERSION=$(grep "^version:" apps/mobile/apps/staff_app/pubspec.yaml | cut -d' ' -f2)
        echo "Version: $VERSION"  # This auto-reads from pubspec

Note: CodeMagic typically reads version from pubspec.yaml automatically. Update only if you have hardcoded version strings.

3. CHANGELOG.md

File: /CHANGELOG.md

Add entry at very top of the table:

| Date | Version | Change |
|---|---|---|
| 2026-03-05 | Staff Mobile 0.2.0 | [Feature descriptions] |
| 2026-03-01 | 0.1.25 | Previous entry... |

📱 Client Mobile App Release

All files to update when releasing client mobile app:

1. Pubspec.yaml

File: /apps/mobile/apps/client_app/pubspec.yaml

# Update format same as staff app
version: 0.2.0+6

2. CodeMagic Configuration

File: /codemagic.yaml

Find the mobile-staff-build workflow (NOT client-build):

workflows:
  mobile-staff-build:  # ← Staff app config
    # ... update pubspec reference for staff ...
    
  mobile-client-build:  # ← Client app config (if separate)
    # ... update pubspec reference for client ...

3. CHANGELOG.md

File: /CHANGELOG.md

| Date | Version | Change |
|---|---|---|
| 2026-03-05 | Client Mobile 0.2.0 | [Feature descriptions] |

🌐 Web Dashboard Release

All files to update when releasing web dashboard:

1. Package.json

File: /apps/web/package.json

{
  "name": "web",
  "private": true,
  "version": "0.1.0",  ← Update this
  // ... other fields ...
}

Format: X.Y.Z (semantic versioning)

2. CHANGELOG.md

File: /CHANGELOG.md

| Date | Version | Change |
|---|---|---|
| 2026-03-05 | Web Dashboard 0.1.0 | [Feature descriptions] |

3. Environment/Build Files (Optional)

Check if there are any other version references:

# Search for version strings
grep -r "0.0.0" apps/web/
grep -r "VERSION" apps/web/

🔧 Command API Backend Release

All files to update when releasing command API:

1. Package.json

File: /backend/command-api/package.json

{
  "name": "@krow/command-api",
  "version": "0.2.0",  ← Update this
  // ... other fields ...
}

2. Docker Configuration (if applicable)

File: /backend/command-api/Dockerfile

If you tag Docker images:

FROM node:20-alpine

# Add label with version
LABEL version="0.2.0"
LABEL description="KROW Command API v0.2.0"

3. CHANGELOG.md

File: /CHANGELOG.md

| Date | Version | Change |
|---|---|---|
| 2026-03-05 | Command API 0.2.0 | [Feature descriptions] |

4. Environment Configuration (if applicable)

If there's a .env or config file:

# Check for any version references
grep -r "VERSION\|version" backend/command-api/

🔧 Core API Backend Release

All files to update when releasing core API:

1. Package.json

File: /backend/core-api/package.json

{
  "name": "@krow/core-api",
  "version": "0.2.0",  ← Update this
  // ... other fields ...
}

2. CHANGELOG.md

File: /CHANGELOG.md

| Date | Version | Change |
|---|---|---|
| 2026-03-05 | Core API 0.2.0 | [Feature descriptions] |

Other Files

Same as Command API (Docker, config files, etc.)

🗄️ DataConnect Database Schema Release

Note: DataConnect versions are typically managed separately through schema versioning.

1. Schema Version File (if exists)

File: Check in /backend/dataconnect/

# Example structure
schema_version: 0.3.0
created_at: 2026-03-05
description: "Schema version 0.3.0 - [description]"

2. CHANGELOG.md

File: /CHANGELOG.md

| Date | Version | Change |
|---|---|---|
| 2026-03-05 | DataConnect Schema 0.3.0 | [Schema changes] |

✅ Release Checklist: Version File Updates

When releasing Staff Mobile v0.2.0

/apps/mobile/apps/staff_app/pubspec.yaml → 0.2.0+X
/codemagic.yaml → version string (if hardcoded)
/CHANGELOG.md → Add entry with date + version
Commit: git add . && git commit -m "chore: staff mobile v0.2.0"
Tag: git tag -a staff-mobile/dev-v0.2.0 -m "Staff Mobile v0.2.0"
Verify: git show staff-mobile/dev-v0.2.0

When releasing Client Mobile v0.2.0

/apps/mobile/apps/client_app/pubspec.yaml → 0.2.0+X
/codemagic.yaml → version string (if hardcoded)
/CHANGELOG.md → Add entry
Complete release process (commit → tag → verify)

When releasing Web Dashboard v0.1.0

/apps/web/package.json → "version": "0.1.0"
/CHANGELOG.md → Add entry
Complete release process

When releasing Command API v0.2.0

/backend/command-api/package.json → "version": "0.2.0"
/backend/command-api/Dockerfile → Label update (optional)
/CHANGELOG.md → Add entry
Complete release process

When releasing Core API v0.2.0

/backend/core-api/package.json → "version": "0.2.0"
/backend/core-api/Dockerfile → Label update (optional)
/CHANGELOG.md → Add entry
Complete release process

When releasing All Products (Synchronized Release)

Staff Mobile: Update pubspec + codemagic
Client Mobile: Update pubspec + codemagic
Web: Update package.json
Command API: Update package.json + docker
Core API: Update package.json + docker
CHANGELOG.md: Add comprehensive entry with all products
Single commit: git commit -m "chore: release all products v1.0.0"

Multiple tags (one per product):

git tag -a staff-mobile/prod-v1.0.0 -m "v1.0.0"
git tag -a client-mobile/prod-v1.0.0 -m "v1.0.0"
git tag -a web-dashboard/prod-v1.0.0 -m "v1.0.0"
git tag -a command-api/prod-v1.0.0 -m "v1.0.0"
git tag -a core-api/prod-v1.0.0 -m "v1.0.0"
git push origin --tags

🔍 Verify All Updates

After updating versions, verify nothing was missed:

# Search for old version strings still remaining
grep -r "0.1.0" apps/mobile/ --include="*.yaml" --include="*.yml" --include="*.json"
grep -r "0.0.0" apps/web/ --include="*.json"
grep -r "0.1.0" backend/ --include="*.json"

# Check CHANGELOG was updated
head -5 CHANGELOG.md

# Verify git status shows all changes
git status

# Review exact changes before committing
git diff CHANGELOG.md
git diff apps/mobile/apps/staff_app/pubspec.yaml
git diff apps/web/package.json

📝 Version Update Template

Copy this template for each release:

#!/bin/bash
# Release: [Product] v[Version]
# Date: [Date]

# Update Staff Mobile
sed -i '' 's/version: 0.1.0+5/version: 0.2.0+6/' apps/mobile/apps/staff_app/pubspec.yaml

# Update CHANGELOG
# (Manual: Add entry at top with date and version)

# Verify
grep "^version:" apps/mobile/apps/staff_app/pubspec.yaml
head -3 CHANGELOG.md

# Commit
git add -A
git commit -m "chore: bump staff mobile to v0.2.0"

# Tag
git tag -a staff-mobile/dev-v0.2.0 -m "Staff Mobile v0.2.0"
git push origin staff-mobile/dev-v0.2.0

# Done!
echo "✅ Release complete. Tag: staff-mobile/dev-v0.2.0"

🚨 Common Mistakes

❌ Forgot to update pubspec.yaml

Result: Version mismatch between code and git tag

❌ Updated CHANGELOG but forgot to update package.json

Result: Version inconsistency, harder to debug

❌ Updated version but didn't increment build number (mobile)

Result: Build tools may fail or warn

❌ Forgot to update codemagic.yaml

Result: CI/CD may deploy old version

❌ Updated multiple files but forgot to commit CHANGELOG

Result: Historical record lost

✅ Always:

Update ALL version files
Update CHANGELOG.md
Commit ALL changes together
Tag after commit
Verify with git show <tag>

🎯 Pro Tips

Tip 1: Use a script to update all versions at once

# Create update-version.sh
VERSION="0.2.0"
sed -i '' "s/version:.*/version: $VERSION/" apps/mobile/apps/staff_app/pubspec.yaml
sed -i '' "s/\"version\".*/\"version\": \"$VERSION\"/" apps/web/package.json
# ... etc for all files

Tip 2: Automate version bumping based on git commit messages

Use conventional commits (feat:, fix:, BREAKING CHANGE:) to auto-determine MAJOR/MINOR/PATCH

Tip 3: Use GitHub Actions to auto-create tags

Create an action that tags on PR merge with version from package.json

Last Updated: 2026-03-05 Maintain: DevOps Team

9.3 KiB Raw Blame History

Version File Locations Reference

📱 Staff Mobile App Release

1. Pubspec.yaml

2. CodeMagic Configuration

3. CHANGELOG.md

📱 Client Mobile App Release

1. Pubspec.yaml

2. CodeMagic Configuration

3. CHANGELOG.md

🌐 Web Dashboard Release

1. Package.json

2. CHANGELOG.md

3. Environment/Build Files (Optional)

🔧 Command API Backend Release

1. Package.json

2. Docker Configuration (if applicable)

3. CHANGELOG.md

4. Environment Configuration (if applicable)

🔧 Core API Backend Release

1. Package.json

2. CHANGELOG.md

Other Files

🗄️ DataConnect Database Schema Release

1. Schema Version File (if exists)

2. CHANGELOG.md

✅ Release Checklist: Version File Updates

When releasing Staff Mobile v0.2.0

When releasing Client Mobile v0.2.0

When releasing Web Dashboard v0.1.0

When releasing Command API v0.2.0

When releasing Core API v0.2.0

When releasing All Products (Synchronized Release)

🔍 Verify All Updates

📝 Version Update Template

🚨 Common Mistakes

🎯 Pro Tips

9.3 KiB

Raw Blame History