Redflag/docs/3_BACKLOG/VERSION_BUMP_CHECKLIST.md

RedFlag Version Bump Checklist

Mandatory for all version increments (e.g., 0.1.23.5 → 0.1.23.6)

This checklist documents ALL locations where version numbers must be updated.

---

⚠️ CRITICAL LOCATIONS (Must Update)

1. Agent Version (Agent Binary)

File: aggregator-agent/cmd/agent/main.go Location: Line ~35, constant declaration Code:

const (
    AgentVersion = "0.1.23.6" // v0.1.23.6: description of changes
)

Verification:

grep -n "AgentVersion.*=" aggregator-agent/cmd/agent/main.go

---

2. Server Config Builder (Primary Source)

File: aggregator-server/internal/services/config_builder.go Locations: 3 places

2a. AgentConfiguration struct comment

Line: ~212
Code:

type AgentConfiguration struct {
    ...
    AgentVersion  string `json:"agent_version"`   // Agent binary version (e.g., "0.1.23.6")
    ...
}

2b. BuildAgentConfig return value

Line: ~276
Code:

return &AgentConfiguration{
    ...
    AgentVersion:   "0.1.23.6",  // Agent binary version
    ...
}

2c. injectDeploymentValues method

Line: ~311
Code:

func (cb *ConfigBuilder) injectDeploymentValues(...) {
    ...
    config["agent_version"] = "0.1.23.6" // Agent binary version (MUST match the binary being served)
    ...
}

Verification:

grep -n "0\.1\.23" aggregator-server/internal/services/config_builder.go

---

3. Server Config (Latest Version Default)

File: aggregator-server/internal/config/config.go Line: ~90 Code:

func Load() (*Config, error) {
    ...
    cfg.LatestAgentVersion = getEnv("LATEST_AGENT_VERSION", "0.1.23.6")
    ...
}

Verification:

grep -n "LatestAgentVersion.*0\.1\.23" aggregator-server/internal/config/config.go

---

4. Server Agent Builder (Validation Comment)

File: aggregator-server/internal/services/agent_builder.go Line: ~79 Code:

func (ab *AgentBuilder) generateConfigJSON(...) {
    ...
    completeConfig["agent_version"] = config.AgentVersion  // Agent binary version (e.g., "0.1.23.6")
    ...
}

Verification:

grep -n "agent_version.*e.g.*0\.1\.23" aggregator-server/internal/services/agent_builder.go

---

📋 FULL UPDATE PROCEDURE

Step 1: Update Agent Version

# Edit file
nano aggregator-agent/cmd/agent/main.go

# Find line with AgentVersion constant and update
# Also update the comment to describe what changed

Step 2: Update Server Config Builder

# Edit file
nano aggregator-server/internal/services/config_builder.go

# Update ALL 3 locations (see section 2 above)

Step 3: Update Server Config Default

# Edit file
nano aggregator-server/internal/config/config.go

# Update the LatestAgentVersion default value

Step 4: Update Server Agent Builder

# Edit file
nano aggregator-server/internal/services/agent_builder.go

# Update the comment to match new version

Step 5: Verify All Changes

# Check all locations have been updated
echo "=== Agent Version ==="
grep -n "AgentVersion.*=" aggregator-agent/cmd/agent/main.go

echo "=== Config Builder ==="
grep -n "0\.1\.23" aggregator-server/internal/services/config_builder.go

echo "=== Server Config ==="
grep -n "LatestAgentVersion.*0\.1\.23" aggregator-server/internal/config/config.go

echo "=== Agent Builder ==="
grep -n "agent_version.*0\.1\.23" aggregator-server/internal/services/agent_builder.go

Step 6: Test Version Reporting

# Build agent
make build-agent

# Run agent with version flag
./redflag-agent --version
# Expected: RedFlag Agent v0.1.23.6

# Build server
make build-server

# Start server (in dev mode)
docker-compose up server

# Check version APIs
curl http://localhost:8080/api/v1/info | grep version

---

🧪 Verification Commands

Quick Version Check

# All critical version locations
echo "Agent main:" && grep "AgentVersion.*=" aggregator-agent/cmd/agent/main.go
echo "Config Builder (return):" && grep -A5 "AgentVersion.*0\.1\.23" aggregator-server/internal/services/config_builder.go | head -3
echo "Server Config:" && grep "LatestAgentVersion" aggregator-server/internal/config/config.go

Comprehensive Check

#!/bin/bash
echo "=== Version Bump Verification ==="
echo ""

echo "1. Agent main.go:"
grep -n "AgentVersion.*=" aggregator-agent/cmd/agent/main.go || echo "❌ NOT FOUND"

echo ""
echo "2. Config Builder struct:"
grep -n "Agent binary version.*0\.1\.23" aggregator-server/internal/services/config_builder.go || echo "❌ NOT FOUND"

echo ""
echo "3. Config Builder return:"
grep -n "AgentVersion.*0\.1\.23" aggregator-server/internal/services/config_builder.go || echo "❌ NOT FOUND"

echo ""
echo "4. Config Builder injection:"
grep -n 'config\["agent_version"\].*0\.1\.23' aggregator-server/internal/services/config_builder.go || echo "❌ NOT FOUND"

echo ""
echo "5. Server config default:"
grep -n "LatestAgentVersion.*0\.1\.23" aggregator-server/internal/config/config.go || echo "❌ NOT FOUND"

echo ""
echo "6. Agent builder comment:"
grep -n "agent_version.*0\.1\.23" aggregator-server/internal/services/agent_builder.go || echo "❌ NOT FOUND"

---

📦 Release Build Checklist

After updating all versions:

• All 4 critical locations updated to same version
• Version numbers are consistent (no mismatches)
• Comments updated to reflect changes
• make build-agent succeeds
• make build-server succeeds
• Agent reports correct version: ./redflag-agent --version
• Server reports correct version in API
• Docker images build successfully: docker-compose build
• Changelog updated (if applicable)
• Git tag created: git tag -a v0.1.23.6 -m "Release v0.1.23.6"
• Commit message includes version: git commit -m "Bump version to 0.1.23.6"

---

🚫 Common Mistakes

Mistake 1: Only updating agent version

Problem: Server still serves old version to agents
Symptom: New agents report old version after registration
Fix: Update ALL locations, especially config_builder.go

Mistake 2: Inconsistent versions

Problem: Different files have different versions
Symptom: Confusion about which version is "real"
Fix: Use search/replace to update all at once

Mistake 3: Forgetting comments

Problem: Code comments still reference old version
Symptom: Documentation is misleading
Fix: Update comments with new version number

Mistake 4: Not testing

Problem: Build breaks due to version mismatch
Symptom: Compilation errors or runtime failures
Fix: Always run verification script after version bump

---

📜 Version History

Version	Date	Changes	Updated By
0.1.23.6	2025-11-13	Scanner timeout configuration API	Octo
0.1.23.5	2025-11-12	Migration system with token preservation	Casey
0.1.23.4	2025-11-11	Agent auto-update system	Casey
0.1.23.3	2025-10-28	Rate limiting, security enhancements	Casey

---

Last Updated: 2025-11-13
Maintained By: Development Team
Related To: ETHOS Principle #4 - Documentation is Immutable