Krow-workspace/VERSION_FILES_REFERENCE.md

# 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`

```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:

```yaml
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:

```markdown
| 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`

```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):

```yaml
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`

```markdown
| 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`

```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`

```markdown
| 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:

```bash
# 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`

```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:

```dockerfile
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`

```markdown
| 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:

```bash
# 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`

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

### 2. CHANGELOG.md
**File**: `/CHANGELOG.md`

```markdown
| 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/`

```yaml
# 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`

```markdown
| 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):
  ```bash
  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:

```bash
# 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:

```bash
#!/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:**
1. Update ALL version files
2. Update CHANGELOG.md
3. Commit ALL changes together
4. Tag after commit
5. Verify with `git show <tag>`

---

## 🎯 Pro Tips

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

```bash
# 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