Skip to main content

Versioning & Build Strategy

Overview​

ItBuild Platform uses a snapshot-based versioning model that provides maximum flexibility and stability for customer projects.

This architecture allows customers to:

  • ✅ Control their upgrade timing
  • ✅ Mix different module versions
  • ✅ Develop without fear of platform changes
  • ✅ Maintain stable production environments

How Builds Work​

Build = Current Master Snapshot​

Key Concept: You cannot request specific old versions. You always get the current version from master.

Customer Request: "Build AuthProxy for my project"
Platform: Checks out master branch (current version: 2.6.0)
Platform: Builds for customer's verified domain
Result: /projects/customer123/AuthProxy/2.6.0/

Customer CANNOT request: "Build version 2.5.0"
No mechanism to build old versions
Master is always the source of truth

Version Accumulation​

As customers request builds over time, they accumulate version snapshots:

Timeline of Builds:

January 2026:
  Master: AuthProxy 2.4.0
  Customer requests build → Gets 2.4.0

February 2026:
  Master: AuthProxy 2.5.0 (new features released)
  Customer requests build → Gets 2.5.0

March 2026:
  Master: AuthProxy 2.6.0 (OAuth added)
  Customer requests build → Gets 2.6.0

Customer's Directory:
/projects/customer123/AuthProxy/
├── 2.4.0/  # Snapshot from January
├── 2.5.0/  # Snapshot from February
└── 2.6.0/  # Snapshot from March

Important: Each build is a snapshot of master at that point in time.

Build On Demand (Not Batch)​

Platform Does NOT Rebuild Everything​

Common Misconception: "Platform releases new version → all customers get rebuilt"

Reality: Platform releases new version → customers keep using what they have

Platform Releases:
Week 1: AuthProxy 2.5.0 released
Week 2: AuthProxy 2.6.0 released
Week 3: AuthProxy 2.7.0 released

Customer Projects (unchanged):
customer001: Still using AuthProxy 2.4.0 ✅
customer002: Still using AuthProxy 2.5.0 ✅
customer003: Still using AuthProxy 2.3.0 ✅

No automatic rebuilds
No forced upgrades
Customers continue working normally

When Builds Happen​

1. Customer Request:

Customer: "Please build latest AuthProxy"
Platform: ./build-module.sh --module AuthProxy --customer-dir /projects/customer123
Result: Customer gets current master version

2. Security Update (Urgent):

# Critical CVE discovered
# Fix committed to master

# Platform team builds for affected customers:
for customer in $(get-affected-customers); do
  ./build-module.sh --module AuthProxy --customer-dir /projects/$customer
done

# Notify customers: "Security update available, please deploy"

3. New Project Setup:

./setup-new-project.sh --customer "NewCorp"
# Builds latest versions of all modules for new customer

When Builds DON'T Happen​

❌ NEVER rebuild for:

  • Internal platform changes
  • Internal refactoring
  • Documentation updates
  • Build process improvements
  • "Just because"

Why?: Existing binaries work fine, no need to rebuild.

Customer Version Independence​

Critical Advantage: Decoupling​

Your development is decoupled from platform releases.

Scenario: Breaking Change Released

Platform Timeline:
Day 1: Release AuthProxy 3.0.0 (header renamed: X-User-Id → X-UserId)

Customer Project:
Day 1-30: Still using AuthProxy 2.5.0 ✅
          Development continues normally
          Nothing breaks
          No surprises

Day 31: Customer reviews migration guide
Day 45: Customer updates their Core module code
Day 60: Customer requests AuthProxy 3.0.0 build
Day 75: Customer deploys to production

Result: Customer handled breaking change on THEIR timeline

No Forced Upgrades​

Platform Situation:
  Released: 2.5.0, 2.6.0, 2.7.0, 3.0.0

Customer Situation:
  Production: 2.5.0    # Stable, proven
  Staging: 2.6.0       # Testing

Customer Decision:
  "We're happy with 2.5.0, no need to upgrade yet"
  "We'll upgrade when WE need new features"
  "No pressure from platform"

Result: Customer controls their stability

Version Mixing (Контуры)​

Modules Are Independent​

Customers can mix different versions of different modules:

# Example Configuration

Production:
  AuthProxy: 2.5.0      # Stable, well-tested
  TrexWallet: 1.2.0     # No issues
  Core: 1.0.5           # Customer's latest

Staging:
  AuthProxy: 2.6.0      # Testing new OAuth feature
  TrexWallet: 1.2.0     # Keep same as production
  Core: 1.0.5           # Keep same as production

Development:
  AuthProxy: 2.6.0      # Latest
  TrexWallet: 1.3.0     # Latest
  Core: 1.0.6-dev       # Development version

Benefits​

Gradual Migration:

Week 1: Test AuthProxy 2.6.0 in staging
Week 2: Deploy AuthProxy 2.6.0 to production
Week 3: Test TrexWallet 1.3.0 in staging
Week 4: Deploy TrexWallet 1.3.0 to production

One module at a time = low risk

Fast Rollback:

# Issue found in AuthProxy 2.6.0
# Rollback to 2.5.0
docker stop customer123-authproxy
docker run -v /projects/customer123/AuthProxy/2.5.0:/app ...

Time: < 5 minutes
Other modules: Unaffected

Bug Isolation:

Test combinations:
- AuthProxy 2.6.0 + TrexWallet 1.2.0 → Bug
- AuthProxy 2.5.0 + TrexWallet 1.2.0 → No bug

Conclusion: Issue is in AuthProxy 2.6.0
Action: Rollback just AuthProxy

Internal vs External Changes​

Internal Changes (No Customer Action)​

Definition: Changes to platform internals that don't affect customer code.

Examples:

  • Internal build process improvements
  • Internal database schema (standard modules)
  • Infrastructure changes

Customer Impact: ❌ NONE - your existing builds continue working

External Changes (Customer Action Required)​

Definition: Changes that break customer Core module integration.

Examples:

  • API endpoint removed
  • Response DTO field removed
  • Request header renamed
  • Authentication flow changed

Workflow:

# Platform team changes header name
git commit -m "feat!: rename header X-User-Id → X-UserId

BREAKING CHANGE: Customer Core modules must update header reading"

# docs-version-tracker agent:
# - Creates migration guide
# - Updates API documentation
# - Updates Templates/Core/
# - Notifies customers

# Customer receives notification:
"AuthProxy 3.0.0 released - Action Required
Header renamed: X-User-Id → X-UserId
Update your Core module code before upgrading"

# Customer timeline:
Week 1-2: Review migration guide
Week 3-4: Update Core module
Week 5: Request AuthProxy 3.0.0 build
Week 6: Test in staging
Week 7: Deploy to production

Customer Impact: ⚠️ CODE UPDATE REQUIRED

Version Strategy Recommendations​

For Platform Team​

Release Cadence:

  • Major versions: Every 6-12 months
  • Minor versions: Every 1-2 months
  • Patch versions: As needed (bugs, security)

Breaking Changes:

  • ⚠️ Minimize breaking changes
  • 📝 Provide detailed migration guides
  • ⏰ Give 2-4 weeks notice before deprecation
  • 🔄 Support transition periods (both old/new headers temporarily)

Communication:

  • 📢 Announce releases in changelog
  • 📧 Notify customers of breaking changes only
  • ❌ Don't notify about internal changes
  • 📚 Keep documentation updated

For Customer Projects​

Conservative (High Stability):

Request builds: Every 2-3 months
Testing period: 2-4 weeks
Versions behind: 1-2 versions

Best for:
- Production-critical systems
- Regulated industries
- Small teams

Balanced (Recommended):

Request builds: Monthly
Testing period: 1-2 weeks
Versions behind: 0-1 versions

Best for:
- Most production systems
- Active development
- Teams with staging

Aggressive (Cutting Edge):

Request builds: Weekly/bi-weekly
Testing period: Few days
Versions behind: 0 (always latest)

Best for:
- Development environments
- New projects
- Strong QA teams

Compatibility Matrix​

Standard Module Compatibility​

AuthProxy Version | Compatible TrexWallet | Compatible Core
------------------|----------------------|----------------
2.6.0             | 1.2.0, 1.3.0         | Any
2.5.0             | 1.2.0, 1.3.0         | Any
3.0.0             | 1.3.0+ (required)    | Requires update

Breaking Compatibility Example:

AuthProxy 3.0.0:
- Changed header: X-User-Id → X-UserId

Impact:
- TrexWallet 1.2.0: Expects X-User-Id ❌ Incompatible
- TrexWallet 1.3.0: Uses X-UserId ✅ Compatible
- Customer Core: Needs code update ⚠️

Migration:
1. Customer updates Core module code
2. Platform builds AuthProxy 3.0.0 for customer
3. Platform builds TrexWallet 1.3.0 for customer
4. Customer tests both together
5. Customer deploys both together

Requesting a Build​

To get new module versions:

  1. Contact ItBuild Team - Request a build for your project
  2. Build is Created - Modules are built and bound to your domain
  3. Test on DEV - Verify in your DEV environment
  4. Deploy to PROD - When ready, deploy all modules together

Best Practices​

Platform Commitments​

  • ✅ Builds on demand, not forced upgrades
  • ✅ Migration guides for breaking changes
  • ✅ Notification only for changes that affect your code
  • ✅ Stable master branch
  • ✅ Backward compatibility maintained

For Customer Projects​

Do:

  • ✅ Request builds when you need features
  • ✅ Test new versions in staging
  • ✅ Pin versions for team consistency
  • ✅ Document what you're using
  • ✅ Keep 2-3 recent versions for rollback

Don't:

  • ❌ Upgrade without testing
  • ❌ Mix incompatible versions
  • ❌ Delete versions in use
  • ❌ Auto-upgrade in production

Monitoring & Tracking​

Platform Tracking​

# Track which customers use which versions
./scripts/customer-version-report.sh

Output:
Customer           | AuthProxy | TrexWallet | Last Build
-------------------|-----------|------------|------------
customer001        | 2.6.0     | 1.3.0      | 2026-02-15
customer002        | 2.5.0     | 1.2.0      | 2026-01-20
customer003        | 2.4.0     | 1.2.0      | 2025-12-10

Summary:
  AuthProxy 2.6.0: 15 customers
  AuthProxy 2.5.0: 20 customers
  AuthProxy 2.4.0: 12 customers

Customer Tracking​

# Check deployed versions
curl http://localhost:8001/health

{
  "module": "AuthProxy",
  "version": "2.5.0",
  "license": {
    "domain": "app.customer123.com",
    "projectId": 17234567890001
  },
  "status": "healthy",
  "buildDate": "2026-01-20"
}

Summary​

Key Concepts​

1. Build = Current Master Snapshot

  • Always builds from master
  • No mechanism for old versions
  • Accumulate versions over time

2. Version Independence

  • Customers control upgrade timing
  • Platform releases don't force upgrades
  • Maximum development stability

3. Version Mixing

  • Modules are independent
  • Mix versions freely
  • Gradual migration
  • Fast rollback

4. Internal vs External

  • Internal: No customer action
  • External: Migration guide + notification
  • Clear separation

Result​

Flexibility + Stability + Control

This architecture provides:

  • ✅ Customer development stability
  • ✅ Platform evolution freedom
  • ✅ Low-risk upgrades
  • ✅ Clear upgrade paths
  • ✅ Production reliability

Win-win for platform team and customer projects.

See Also​