Dependency hell

[ocots]

Formalization of the Dependency Update Problem with Integration Testing

1. Problem Description

1.1 Context

In an ecosystem of interdependent packages, we develop several packages A, B, C, ... simultaneously. These packages have dependency relationships and declare version compatibility constraints.

Central Problem: When introducing a breaking change in a base package C, we want to:

1. Test the impact on dependent packages before publishing
2. Progressively adapt all dependent packages
3. Ensure end users are not affected during the transition
4. Maintain the ability to test packages under development

1.2 The Integration Testing Paradox

When we modify C and want to test B (which depends on C), compatibility constraints can prevent building the test environment:

• B (development version) requires C v2
• A (stable version) requires B v1 and C v1
• Impossible to test A with the new B because constraints on C are contradictory

---

2. Mathematical Modeling

2.1 Simple Dependency Graph (Diamond)

Consider the minimal case with three packages forming a "diamond":

    A
   ╱ ╲
  B   │
   ╲ ╱
    C

Relations:

• A depends on B and C
• B depends on C
• C is the base package (no dependencies)

2.2 Formal Definitions

Universe:

• P = {A, B, C}: set of packages
• V = set of versions, for each package p ∈ P, we denote V_p as the set of its versions
• Example: V_C = {v1, v2}, V_B = {v1, v1'}, V_A = {v1, v1'}

Graph Node:

• A node is a pair (p, v) where p ∈ P and v ∈ V_p
• Notation: (Package, Version)

Compatibility Function:

For each node (p, v), we define:

Compat(p, v) : P → 𝒫(V)

where 𝒫(V) is the power set (all subsets) of versions.

Interpretation: Compat(p, v)(p') gives the set of versions of p' compatible with (p, v).

Example (strict compatibility):

Compat(A, v1) = {B ↦ {v1}, C ↦ {v1}}
Compat(B, v1) = {C ↦ {v1}}
Compat(C, v1) = {}

Example (compatibility with range):

Compat(A, v1') = {B ↦ {v1}, C ↦ {v1, v2}}

2.3 Configuration and Resolution

Configuration:

A configuration K is a set of nodes:

K ⊆ {(p, v) | p ∈ P, v ∈ V_p}

with the version uniqueness constraint:

∀(p₁, v₁), (p₂, v₂) ∈ K : p₁ = p₂ ⟹ v₁ = v₂

Valid Configuration:

A configuration K is valid for a target node (p_target, v_target) if:

1. (p_target, v_target) ∈ K

2. Dependency Closure:

   ∀(p, v) ∈ K, ∀p' ∈ dependencies_of(p) :
     ∃v' such that (p', v') ∈ K and v' ∈ Compat(p, v)(p')
   

SAT Problem:

Given (p_target, v_target), does there exist a valid configuration?

2.4 Resolution Algorithm with Preference

When multiple versions satisfy constraints for a package p':

Maximal Resolution Strategy:

If S = {v ∈ V_p' | all constraints are satisfied with v}
Then choose v* = max(S)

where max is defined according to a total order on versions (typically chronological order).

---

3. System States and Evolution

3.1 Initial State (Baseline)

Available Nodes:

N₀ = {(A, v1), (B, v1), (C, v1)}

Compatibilities:

Compat(A, v1) = {B ↦ {v1}, C ↦ {v1}}
Compat(B, v1) = {C ↦ {v1}}
Compat(C, v1) = {}

Valid Configuration for A v1:

K₀ = {(A, v1), (B, v1), (C, v1)}

3.2 State After Creating C v2

New Nodes:

N₁ = N₀ ∪ {(C, v2)}

Compatibilities unchanged for A v1 and B v1

Valid Configuration for A v1: K₀ (identical, as A v1 doesn't know about C v2)

3.3 State with B' (development version)

We create B v1' that uses C v2:

Nodes:

N₂ = N₁ ∪ {(B, v1')}

New Compatibility:

Compat(B, v1') = {C ↦ {v2}}

Unsatisfiability Problem:

Testing (A, v1) with (B, v1'):

Sought Configuration: K = {(A, v1), (B, v1'), (C, ?)}

Constraints on C:
  - From (A, v1): C ∈ {v1}
  - From (B, v1'): C ∈ {v2}

Intersection: {v1} ∩ {v2} = ∅

❌ UNSATISFIABLE

3.4 Solution: Preventive Widening

Modify A before the problem:

N₃ = N₂ ∪ {(A, v1')}

Compat(A, v1') = {B ↦ {v1}, C ↦ {v1, v2}}

Test 1: (A, v1') alone

K₁ = {(A, v1'), (B, v1), (C, ?)}

Constraints on C:
  - From (A, v1'): C ∈ {v1, v2}
  - From (B, v1): C ∈ {v1}

Intersection: {v1, v2} ∩ {v1} = {v1}
Resolution: choose C = v1

✅ K₁ = {(A, v1'), (B, v1), (C, v1)} VALID

Test 2: (A, v1') with (B, v1')

K₂ = {(A, v1'), (B, v1'), (C, ?)}

Constraints on C:
  - From (A, v1'): C ∈ {v1, v2}
  - From (B, v1'): C ∈ {v2}

Intersection: {v1, v2} ∩ {v2} = {v2}
Resolution: choose C = v2

✅ K₂ = {(A, v1'), (B, v1'), (C, v2)} VALID

---

4. Abstract Migration Workflow

Phase 1: Preparation (widening compatibilities)

Before creating C v2, widen compatibilities:

For all packages p depending on C:

Compat(p, v_current) := Compat(p, v_current)[C ↦ {v1, v2}]

Guaranteed Property:

• Existing configurations remain valid (v1 is still in the set)
• New configurations with v2 become possible

Phase 2: Introduction of C v2

Create (C, v2) possibly with a pre-release version:

(C, v2-beta) where v1 < v2-beta < v2

Advantages of pre-releases:

• Resolvers ignore pre-releases by default
• Requires explicit declaration in Compat to be used
• Normal users stay on v1

Phase 3: Adaptation of Direct Dependents

For each package B directly depending on C:

1. Create (B, v_new) with:

   Compat(B, v_new) = {..., C ↦ {v2}}
   

2. Integration tests on A pass because:

   Compat(A, v_current) = {..., C ↦ {v1, v2}}
   

   allows resolution with C v2

Phase 4: Adaptation of Indirect Dependents

For each package A depending on B:

If necessary (breaking changes in B), adapt A.

Otherwise, simply update compatibility ranges to accept new versions of B.

Phase 5: Stabilization

1. Publish C v2 (stable version, without pre-release)

2. Optionally, tighten compatibilities:

   Compat(p, v) := Compat(p, v)[C ↦ {v2}]
   

   to force user migration

---

5. Guaranteed Properties

5.1 Non-Regression

Property: If a configuration K_i is valid in state N_i, it remains resolvable in N_{i+1} after adding new versions.

Proof: Adding new nodes doesn't invalidate old configurations because old compatibilities remain unchanged.

5.2 Progressive Testability

Property: With preventive widening of compatibilities, we can test packages under development without blocking existing tests.

Reason: Version ranges {v1, v2} allow the resolver to choose the appropriate version depending on context.

5.3 User Isolation

Property: End users are not affected during transition if we use pre-releases.

Mechanism: Resolvers ignore pre-releases by default, so users stay on stable versions until final publication.

---

6. Complexity and Limitations

6.1 SAT Problem Complexity

The dependency resolution problem is NP-complete in the general case.

However, with heuristics (maximal version choice) and reasonable constraints, it becomes practical.

6.2 Combinatorial Explosion

With n packages each having k compatible versions:

Number of possible configurations: O(k^n)

Practical Solution:

• Limit the number of simultaneously compatible versions
• Use pre-releases for progressive transition
• Constrain migration order (bottom-up in dependency graph)

6.3 Transitive Conflicts

In a complex graph with many diamonds, conflicts can emerge even with preventive widening.

Example:

    A
  ╱  ╲
 B    D
  ╲  ╱
   C

If B requires C v2 and D requires C v1, A cannot use them simultaneously even with a widened range.

Solution: Coordinate migration (migrate B and D together).

---

7. Conclusion

7.1 Key Principles

1. Preventive Widening: Allow multiple versions in Compat before the breaking change
2. Pre-releases: Isolate end users during development
3. Bottom-up Migration: Adapt base packages first, then move up the graph
4. Continuous Testing: Breakage tests verify configuration validity at each step

7.2 Generalization

This workflow applies to any package ecosystem with:

• A semantic versioning system
• A constraint-based dependency resolver
• Support for version ranges or pre-releases
• A CI system for integration testing

Examples: Julia (Pkg.jl), Rust (Cargo), JavaScript (npm/pnpm), Python (pip/poetry), etc.

[ocots]

Solutions to the Dependency Update Problem: A Comparative Analysis

1. Overview of Approaches

The dependency update problem with integration testing can be solved through several architectural and tooling approaches. Each has different trade-offs in terms of complexity, flexibility, and scalability.

Categories of Solutions:

1. Monorepo approaches - All packages in a single repository
2. Version range strategies - Allowing multiple compatible versions
3. Local override mechanisms - Development-time dependency substitution
4. Pre-release workflows - Staged rollout with version suffixes
5. Workspace systems - Hybrid between monorepo and polyrepo

---

2. Monorepo Approach

2.1 Concept

All packages live in a single repository with a shared version control history. Dependencies between packages use local paths rather than published versions during development.

Key Insight: Version constraints are effectively ignored for internal packages - the build system always uses the latest local code.

2.2 Architecture

monorepo/
├── packages/
│   ├── base/          (C)
│   ├── models/        (B) 
│   └── control/       (A)
├── BUILD              (build definitions)
└── WORKSPACE          (workspace config)

Dependency Resolution:

• Internal dependencies: resolved to local paths
• External dependencies: resolved from registry
• No version conflicts between internal packages (always latest)

2.3 Who Uses This

Google (Bazel)

Scale:

• ~2 billion lines of code
• ~9 million source files
• ~35 million commits
• Thousands of engineers

Build System: Bazel

# packages/models/BUILD
cc_library(
    name = "models",
    srcs = ["models.cc"],
    deps = [
        "//packages/base:base",  # Local dependency
    ],
)

Key Features:

• Hermetic builds (reproducible)
• Incremental compilation
• Remote caching
• Distributed execution

Advantages:

• Atomic changes across packages
• No version coordination needed
• Refactoring across boundaries is easy
• Single CI pipeline

Challenges:

• Requires sophisticated build tooling
• CI must test all affected packages
• Scales to billions of lines but requires infrastructure

Facebook/Meta (Buck2)

Similar to Google's approach:

• Single repository for most code
• Buck2 build system (successor to Buck)
• Atomic cross-package changes
• Extensive CI infrastructure

Microsoft (parts of Windows, parts of Office)

• Some divisions use monorepo
• Azure DevOps itself developed in monorepo
• Git Virtual File System (GVFS) for performance

2.4 Advantages

✅ No version coordination problems - always use latest local code
✅ Atomic changes - breaking changes and fixes in one commit
✅ Easy refactoring - tools can refactor across packages
✅ Consistent testing - single CI pipeline tests everything
✅ Simplified dependency management - no need to publish intermediate versions

2.5 Disadvantages

❌ Tooling requirements - needs sophisticated build system
❌ CI complexity - must determine what to test after changes
❌ Repository size - can become very large
❌ Access control - harder to restrict access to specific packages
❌ External contributors - higher barrier to entry
❌ Build performance - requires caching and incremental builds

---

3. Version Range Strategies

3.1 Concept

Allow packages to declare compatibility with multiple versions through ranges. The resolver picks the best version that satisfies all constraints.

Key Insight: Preventive widening of compatibility ranges allows testing unreleased versions without breaking existing users.

3.2 Implementation in Different Ecosystems

Rust (Cargo)

Syntax:

[dependencies]
base = "1"           # Any 1.x.y version
base = ">=1.5, <2"   # Explicit range
base = "1.5"         # 1.5.x (caret by default)

Pre-release support:

base = "2.0.0-beta"  # Explicitly opt into pre-releases

Who uses it:

• Rust ecosystem (crates.io)
• 150,000+ crates
• Extensive use of semver ranges

JavaScript (npm/pnpm/yarn)

Syntax:

{
  "dependencies": {
    "base": "^1.0.0",      // 1.x.x (caret)
    "base": "~1.5.0",      // 1.5.x (tilde)
    "base": ">=1.0.0 <2.0.0"
  }
}

Pre-release tags:

"base": "2.0.0-beta.1"

Who uses it:

• npm registry: 2.5+ million packages
• Most JavaScript projects
• Companies: Netflix, LinkedIn, Airbnb

Python (pip/poetry)

Syntax (Poetry):

[tool.poetry.dependencies]
base = "^1.0"        # 1.x.x
base = ">=1.5,<2.0"  # Explicit range

Who uses it:

• PyPI: 500,000+ packages
• Scientific computing community
• Companies: Instagram, Spotify, Dropbox

Julia (Pkg.jl)

Syntax:

[compat]
CTBase = "1"           # 1.x.x
CTBase = "1.5"         # 1.5.x
CTBase = "1, 2"        # Both major versions
CTBase = "0.16, 0.17.0-"  # Include pre-releases

Who uses it:

• Julia ecosystem
• Scientific computing
• ~10,000 registered packages

3.3 Advantages

✅ Flexibility - packages can work with multiple versions
✅ Standard tooling - built into package managers
✅ Gradual migration - old and new versions coexist
✅ User choice - resolver picks best version for context
✅ No special infrastructure - works with existing registries

3.4 Disadvantages

❌ Range maintenance - need to test with all claimed compatible versions
❌ False positives - declaring compatibility doesn't guarantee it works
❌ Resolver complexity - can fail with complex constraint systems
❌ Version sprawl - users may end up with many versions installed

---

4. Local Override Mechanisms

4.1 Concept

During development, temporarily substitute registry packages with local versions. Production builds use published versions.

Key Insight: Separate development configuration from production, allowing testing without publishing.

4.2 Implementation Patterns

Cargo (Rust) - [patch]

# Root Cargo.toml
[patch.crates-io]
base = { path = "../base-dev" }

# Or from git branch
base = { git = "https://github.com/org/base", branch = "v2-dev" }

Behavior:

• All dependencies on base use the patched version
• Works transitively (if B depends on base, A gets the patch too)
• Ignored in published packages

npm/yarn - link and resolutions

npm link:

cd ../base
npm link

cd ../control
npm link base  # Use local version

Yarn resolutions:

{
  "resolutions": {
    "base": "file:../base-dev"
  }
}

Python - editable installs

pip install -e ../base-dev  # Editable mode

Poetry:

[tool.poetry.dependencies]
base = { path = "../base-dev", develop = true }

Julia - Pkg.develop()

using Pkg
Pkg.develop(path="../CTBase-dev")
# Or from git
Pkg.develop(url="https://github.com/org/CTBase", rev="v2-dev")

Key feature: Completely ignores version constraints for developed packages.

4.3 Who Uses This

Common in:

• Open source development (testing PRs locally)
• Corporate environments with multiple related packages
• Any polyrepo setup needing integration testing

Examples:

• Rust community: Extensive use of [patch] for testing
• Node.js ecosystem: npm link is standard practice
• Python data science: Often develop multiple packages together

4.4 Advantages

✅ No repository changes - keeps polyrepo structure
✅ Temporary - easy to switch back to published versions
✅ Flexible - can override specific packages
✅ Works with existing tools - built into package managers
✅ CI integration - can use in automated tests

4.4 Disadvantages

❌ Manual setup - developers must configure locally
❌ Not in production - overrides don't affect published packages
❌ State management - easy to forget active overrides
❌ Team coordination - each developer configures independently

---

5. Workspace Systems

5.1 Concept

Hybrid approach: multiple packages in one repository, but treated as separate during publication. Internal dependencies use local code during development, published versions in production.

Key Insight: Get monorepo benefits during development, polyrepo benefits for publication.

5.2 Implementation

Cargo Workspaces (Rust)

# Root Cargo.toml
[workspace]
members = [
    "packages/base",
    "packages/models",
    "packages/control",
]

Behavior:

• Shared target directory (faster builds)
• Shared Cargo.lock (consistent versions)
• Internal packages use local code
• External packages from registry
• Each package publishes independently

npm/yarn/pnpm Workspaces

{
  "workspaces": [
    "packages/*"
  ]
}

pnpm workspace protocol:

{
  "dependencies": {
    "base": "workspace:*"  // Always use local version
  }
}

Poetry Workspaces (Python)

Still experimental, but supported via:

[tool.poetry.dependencies]
base = { path = "../base", develop = true }

Lerna/Nx (JavaScript)

Lerna:

• Monorepo management tool
• Handles versioning and publishing
• Links packages automatically

Nx:

• Advanced build system
• Computation caching
• Dependency graph analysis
• Affected command (test only changed packages)

5.3 Who Uses This

Rust Ecosystem

• tokio: Async runtime (workspace with 50+ crates)
• serde: Serialization framework
• diesel: Database ORM
• Most complex Rust projects

JavaScript Ecosystem

• Babel: Compiler (monorepo with 140+ packages)
• Jest: Testing framework
• React: UI library (Meta's React monorepo)
• Vue: Progressive framework
• Angular: Google's framework

Examples of Corporate Usage

• Google: Uses Bazel but some teams use workspaces
• Microsoft: VS Code uses workspaces
• Stripe: Multiple internal packages in workspaces
• Shopify: Ruby and JS packages in workspaces

5.4 Advantages

✅ Best of both worlds - monorepo dev, polyrepo publish
✅ Independent versioning - packages can have different versions
✅ Shared tooling - common CI, linting, formatting
✅ Atomic changes - can change multiple packages in one PR
✅ Easier testing - automatic use of local versions
✅ Selective publishing - only publish changed packages

5.5 Disadvantages

❌ Complexity - more setup than pure monorepo or polyrepo
❌ Tooling support varies - not all ecosystems have mature workspace support
❌ Version coordination - still need to manage compat declarations
❌ CI complexity - need to detect which packages changed

---

6. Pre-release Workflow Strategy

6.1 Concept

Use semantic versioning pre-release identifiers (alpha, beta, rc) to stage rollouts. Users opt-in to pre-releases explicitly.

Key Insight: Pre-releases are published but ignored by default, allowing safe testing in production-like environments.

6.2 Implementation Pattern

Version progression:

1.5.0 (stable) 
  → 2.0.0-alpha.1 (early testing)
  → 2.0.0-beta.1 (feature complete)
  → 2.0.0-rc.1 (release candidate)
  → 2.0.0 (stable)

Resolver behavior:

• By default: ignores all pre-releases
• With opt-in: "base": "2.0.0-beta" includes betas
• Transitively: if A depends on B beta, A must accept it

6.3 Best Practices

Progressive compatibility widening:

1. Before breaking change:

   [compat]
   base = "1, 2.0.0-"  # Accept v1 and all v2 pre-releases

2. Release base as pre-release:

   base v2.0.0-beta.1
   

3. Test dependent packages: CI uses beta automatically

4. Adapt dependents incrementally

5. Final release:

   base v2.0.0 (stable)
   

6.4 Who Uses This

Rust Ecosystem

• Extensive use of pre-releases for breaking changes
• Example: Tokio's 1.0 release had multiple alphas/betas
• Crater testing: automated testing of all crates

JavaScript Ecosystem

• React releases (16.0.0-alpha, beta, rc)
• Next.js canary releases
• TypeScript beta/RC versions

Python

• Django pre-releases (4.0a1, 4.0b1, 4.0rc1)
• NumPy pre-releases for major versions

6.5 Advantages

✅ Safe rollout - users must explicitly opt-in
✅ Standard semver - no custom tooling needed
✅ Production testing - can test in real environments
✅ Reversible - easy to roll back to stable
✅ Clear communication - version indicates stability

6.6 Disadvantages

❌ Multiple releases - need to publish several versions
❌ Testing burden - should test each pre-release
❌ User confusion - some users accidentally use pre-releases
❌ Registry pollution - many versions in registry

---

7. Comparative Analysis

7.1 Decision Matrix

Approach	Setup Complexity	Dev Experience	CI Complexity	Scale	External Contributors
Monorepo (Bazel)	Very High	Excellent	Very High	Excellent	Difficult
Workspaces	Medium	Excellent	Medium	Good	Medium
Version Ranges	Low	Good	Low	Good	Easy
Local Overrides	Low	Medium	Medium	Good	Easy
Pre-releases	Low	Medium	Low	Excellent	Easy

7.2 Choosing an Approach

Use Monorepo If:

• You have resources for sophisticated build systems
• Most code is internal
• Team is co-located or well-coordinated
• Atomic cross-package changes are critical
• Examples: Google-scale companies

Use Workspaces If:

• You want monorepo benefits with polyrepo flexibility
• Packages are related but independently published
• Medium to large team (10-100+ developers)
• Need independent versioning
• Examples: Most modern open-source projects

Use Version Ranges If:

• Simple ecosystem with few packages
• Standard package manager is sufficient
• External contributors are common
• Packages have clear compatibility boundaries
• Examples: Most polyrepo setups

Use Local Overrides If:

• Existing polyrepo that works well
• Infrequent cross-package changes
• Small team with good communication
• Don't want to restructure repositories
• Examples: Established projects, corporate polyrepos

Use Pre-releases If:

• Any of the above (complementary strategy)
• Public-facing packages
• Need staged rollout
• Want production testing before final release
• Examples: Critical infrastructure packages

---

8. Hybrid Approaches

8.1 Combining Strategies

Real-world projects often combine multiple approaches:

Example 1: Workspace + Pre-releases

Development: workspace with local versions
CI: test with pre-releases
Production: published stable versions

Example 2: Local Overrides + Version Ranges

Development: local overrides for active work
Published: wide version ranges for compatibility

Example 3: Monorepo + External Packages

Internal: monorepo with Bazel
External: published as separate packages with version ranges

8.2 Real-World Examples

Google

• Internal: Monorepo with Bazel
• External: Publishes packages (TensorFlow, etc.) with semantic versioning
• Bridge between internal and external through release process

Microsoft

• Internal: Mix of monorepo (some teams) and polyrepo
• External: TypeScript, VS Code published with pre-releases
• Open source: Workspace-based development

Meta/Facebook

• Internal: Monorepo
• Open source: React, Jest use workspaces
• npm packages: Published with semantic versioning

---

9. Recommendations for Different Scales

9.1 Small Projects (1-10 packages, 1-5 developers)

Recommended: Version ranges + local overrides

• Low setup cost
• Standard tooling
• Easy for new contributors

Workflow:

1. Develop with local overrides
2. Widen version ranges preventively
3. Use pre-releases for testing
4. Publish stable versions

9.2 Medium Projects (10-50 packages, 5-50 developers)

Recommended: Workspaces + pre-releases

• Better coordination than polyrepo
• Maintains publication flexibility
• Scales to moderate complexity

Workflow:

1. Workspace repository structure
2. Automated CI for affected packages
3. Pre-release workflow for breaking changes
4. Independent package versioning

9.3 Large Projects (50+ packages, 50+ developers)

Recommended: Full monorepo (if resources allow) or advanced workspaces

• Bazel or similar build system
• Extensive CI infrastructure
• Automated refactoring tools
• Dedicated developer experience team

Workflow:

1. Single repository with build system
2. Automated testing of all affected code
3. Tool-assisted refactoring
4. Release tooling for external packages

---

10. Tooling Ecosystem Summary

10.1 Build Systems

Tool	Language	Scale	Complexity	Notable Users
Bazel	Multi-language	Very Large	Very High	Google, Uber, LinkedIn
Buck2	Multi-language	Large	High	Meta
Pants	Multi-language	Large	High	Twitter, Foursquare
Nx	JavaScript	Medium-Large	Medium	Nrwl, many enterprises
Turborepo	JavaScript	Medium	Low-Medium	Vercel customers
Lerna	JavaScript	Small-Medium	Low	Babel, Jest (legacy)

10.2 Package Managers with Workspace Support

Tool	Language	Workspace Quality	Notable Features
Cargo	Rust	Excellent	Shared lock file, integrated
pnpm	JavaScript	Excellent	Efficient storage, workspace protocol
Poetry	Python	Good	Modern dependency resolution
npm/yarn	JavaScript	Good	Standard, widely adopted
Pkg.jl	Julia	Excellent	Develop mode, artifact system

---

11. Conclusion

11.1 Key Takeaways

1. No silver bullet: Each approach has trade-offs
2. Scale matters: Solution should match team/project size
3. Tooling investment: Better tools enable better workflows
4. Hybrid approaches work: Combine strategies as needed
5. Evolution is okay: Start simple, scale as needed

11.2 General Principles

For the dependency update problem specifically:

• Preventive action works better than reactive fixes
• Version ranges + pre-releases solve 80% of cases with minimal setup
• Workspaces provide excellent middle ground for related packages
• Monorepos are powerful but require significant investment
• Local overrides are essential for any polyrepo workflow

Success factors:

• Clear versioning policy
• Automated testing (breakage detection)
• Good CI infrastructure
• Team communication and coordination
• Documentation of workflow

[ocots]

CTBase v0.16 → v0.17 Migration Guide with Pre-release Strategy

1. Overview

This guide explains how to migrate CTBase from v0.16.0 to v0.17.0 (a breaking change) using a pre-release strategy that ensures:

• Normal users remain unaffected during development
• All dependent packages can be tested before final release
• The breakage CI workflow continues to function
• Migration happens progressively without coordination issues

---

2. Package Dependency Graph

CTBase (base package)
    ↑
    ├─── CTModels
    ├─── CTParser ────→ CTModels
    ├─── CTDirect ────→ CTModels
    ├─── CTFlows ─────→ CTModels
    └─── OptimalControl → CTDirect, CTModels, CTFlows, CTParser

Current state:

• All packages at v0.X.Y
• All depend on CTBase v0.16

Goal:

• Migrate to CTBase v0.17 (breaking changes)
• Test all packages during migration
• Keep users on v0.16 until everything is ready

---

3. How Julia's Pkg.jl Resolver Works

3.1 Version Selection Rules

Julia follows Semantic Versioning 2.0.0 strictly with specific resolution rules:

Rule 1: Version Ordering

0.16.0 < 0.16.1 < 0.17.0-alpha.1 < 0.17.0-beta.1 < 0.17.0-rc.1 < 0.17.0

Pre-releases are considered lower than the corresponding stable release.

Rule 2: Pre-release Ignoring

By default, Pkg ignores pre-releases completely.

using Pkg
Pkg.add("CTBase")  # Will install 0.16.0, ignores 0.17.0-beta.1

Even if 0.17.0-beta.1 exists in the registry, users get 0.16.0.

Rule 3: Explicit Pre-release Opt-in

To use a pre-release, you must explicitly allow it in compat:

# This ignores pre-releases
[compat]
CTBase = "0.16"

# This accepts pre-releases
[compat]
CTBase = "0.16, 0.17.0-"

The notation 0.17.0- means "all pre-releases of 0.17.0" (alpha, beta, rc).

Rule 4: Resolver Intersection

When multiple packages have constraints, the resolver finds the intersection:

# Package A requires: CTBase ∈ {0.16, 0.17.0-}
# Package B requires: CTBase ∈ {0.17.0-}
# Intersection: {0.17.0-}
# Result: Pkg installs 0.17.0-beta.1 (latest pre-release)

Rule 5: Maximum Version Preference

When multiple versions satisfy constraints, Pkg chooses the highest:

# Available: 0.17.0-beta.1, 0.17.0-beta.2
# Constraints satisfied by both
# Result: Pkg installs 0.17.0-beta.2

3.2 Example: User Installing OptimalControl

Scenario 1: Before migration (stable)

using Pkg
Pkg.add("OptimalControl")

Registry state:

• CTBase: v0.16.0 (stable)
• OptimalControl: declares CTBase = "0.16"

Result: Installs CTBase v0.16.0 ✅

Scenario 2: During migration (beta available)

using Pkg
Pkg.add("OptimalControl")

Registry state:

• CTBase: v0.16.0 (stable), v0.17.0-beta.1 (pre-release)
• OptimalControl: declares CTBase = "0.16, 0.17.0-" (widened preventively)

Result: Still installs CTBase v0.16.0 ✅

Why? Because 0.17.0-beta.1 is a pre-release, Pkg prefers the stable v0.16.0.

Scenario 3: After CTModels migration

using Pkg
Pkg.add(["OptimalControl", "CTModels"])

Registry state:

• CTBase: v0.16.0, v0.17.0-beta.1
• CTModels: declares CTBase = "0.17.0-" (requires beta)
• OptimalControl: declares CTBase = "0.16, 0.17.0-"

Result: Installs CTBase v0.17.0-beta.1 ✅

Why? Resolver finds intersection:

• CTModels constraint: {0.17.0-}
• OptimalControl constraint: {0.16, 0.17.0-}
• Intersection: {0.17.0-}
• Maximum: v0.17.0-beta.1

Scenario 4: After stable v0.17.0 release

using Pkg
Pkg.add("OptimalControl")

Registry state:

• CTBase: v0.16.0, v0.17.0-beta.1, v0.17.0 (stable)
• OptimalControl: declares CTBase = "0.16, 0.17"

Result: Installs CTBase v0.17.0 ✅

Why? v0.17.0 (stable) is now the maximum in the allowed set.

---

4. Migration Workflow with Pre-releases

Phase 1: Preventive Compatibility Widening

Goal: Prepare all packages to accept CTBase v0.17 pre-releases

Step 1.1: CTModels

File: CTModels/Project.toml

name = "CTModels"
uuid = "..."
version = "0.10.2"  # Bump patch version

[deps]
CTBase = "..."

[compat]
CTBase = "0.16, 0.17.0-"  # ← Changed from "0.16"
julia = "1.9"

Actions:

1. Create PR: "Prepare for CTBase v0.17"
2. No code changes - only widen compat
3. CI runs with CTBase v0.16.0 (still stable) → ✅ passes
4. Merge PR
5. Register CTModels v0.10.2

User impact: None - users still get CTBase v0.16.0

Step 1.2: CTParser

[compat]
CTBase = "0.16, 0.17.0-"
CTModels = "0.10"  # Accept new CTModels version

Actions: PR → CI → Merge → Register CTParser v0.8.4

Step 1.3: CTDirect

[compat]
CTBase = "0.16, 0.17.0-"
CTModels = "0.10"

Actions: PR → CI → Merge → Register CTDirect v0.12.6

Step 1.4: CTFlows

[compat]
CTBase = "0.16, 0.17.0-"
CTModels = "0.10"

Actions: PR → CI → Merge → Register CTFlows v0.6.3

Step 1.5: OptimalControl

[compat]
CTBase = "0.16, 0.17.0-"
CTDirect = "0.12"
CTModels = "0.10"
CTFlows = "0.6"
CTParser = "0.8"

Actions: PR → CI → Merge → Register OptimalControl v0.15.9

Result after Phase 1:

• ✅ All packages registered with widened compat
• ✅ Users still get CTBase v0.16.0 (stable)
• ✅ System ready for beta testing

---

Phase 2: CTBase v0.17.0-beta.1 Development

Goal: Develop breaking changes and release as pre-release

Step 2.1: Develop Changes

Branch: feature/v0.17

• Implement breaking changes in CTBase
• Update documentation
• Run CTBase tests locally

Step 2.2: Run Breakage CI

Your breakage workflow automatically tests:

# From .github/workflows/breakage.yml
strategy:
  matrix:
    pkg:
      - {user: control-toolbox, repo: CTModels.jl, group: ALL}
      - {user: control-toolbox, repo: CTParser.jl, group: ALL}
      - {user: control-toolbox, repo: CTDirect.jl, group: ALL}
      - {user: control-toolbox, repo: CTFlows.jl, group: ALL}
      - {user: control-toolbox, repo: OptimalControl.jl, group: ALL}

What happens:

1. For each package, tests both:

   • Stable version (from registry)
   • Main branch (from GitHub)

2. The workflow does:

# For stable version
Pkg.add(name="CTModels")  # Gets registry version

# For main branch  
Pkg.add(url="https://github.com/control-toolbox/CTModels.jl", rev="main")

3. Both use your CTBase from the feature branch

Expected result:

• ❌ Most breakage tests fail (expected - breaking changes!)
• This tells you what needs to be fixed in each package

Step 2.3: Release Beta

File: CTBase/Project.toml

name = "CTBase"
uuid = "..."
version = "0.17.0-beta.1"  # ← Pre-release version

Actions:

1. Create PR to main
2. Merge
3. Register in General registry: @JuliaRegistrator register

Registry after registration:

CTBase
├── v0.16.0 (stable)
└── v0.17.0-beta.1 (pre-release)

User impact:

using Pkg
Pkg.add("CTBase")  # Still gets v0.16.0 ✅
Pkg.status()
# [1234...] CTBase v0.16.0

Users are completely isolated from the beta.

---

Phase 3: Migrate CTModels to v0.17

Goal: Adapt CTModels to work with CTBase v0.17.0-beta.1

Step 3.1: Adapt Code

Branch: upgrade/ctbase-v0.17

• Fix code to work with CTBase v0.17 API changes
• Run CTModels tests locally with CTBase v0.17.0-beta.1:

using Pkg
Pkg.develop(path="../CTBase")  # Or use beta from registry
Pkg.test("CTModels")

Step 3.2: Update Compat

File: CTModels/Project.toml

name = "CTModels"
version = "0.11.0"  # ← Bump MINOR (breaking since v0.x)

[compat]
CTBase = "0.17.0-"  # ← Now REQUIRES beta (removed 0.16)

Why bump minor? In semantic versioning, for v0.x packages, minor bumps indicate breaking changes (v0.x is considered pre-1.0 development).

Step 3.3: Test with Breakage CI

When you push this PR, your breakage workflow tests:

1. OptimalControl@stable with CTModels@PR:

   # OptimalControl from registry declares: CTBase = "0.16, 0.17.0-"
   # CTModels@PR declares: CTBase = "0.17.0-"
   # Intersection: 0.17.0-
   # Result: ✅ Resolves to CTBase v0.17.0-beta.1

2. OptimalControl@main with CTModels@PR:

   # Same resolution
   # Result: ✅ Should work if no API changes in CTModels

If tests pass: CTModels changes are backward compatible! 🎉

If tests fail: OptimalControl needs updates too.

Step 3.4: Register CTModels

Actions:

1. Merge PR
2. Register CTModels v0.11.0

Registry state:

CTBase:   0.16.0, 0.17.0-beta.1
CTModels: 0.10.2 (uses CTBase 0.16, 0.17.0-)
          0.11.0 (uses CTBase 0.17.0-)

User impact:

# User installing just OptimalControl
Pkg.add("OptimalControl")
# Gets: CTBase 0.16.0, CTModels 0.10.2 ✅

# User explicitly wanting CTModels latest
Pkg.add("CTModels")  
# Gets: CTModels 0.11.0, CTBase 0.17.0-beta.1
# (because CTModels 0.11.0 requires it)

# This is opt-in behavior ✅

---

Phase 4: Migrate Remaining Packages

For each package (CTParser, CTDirect, CTFlows, OptimalControl):

If Breakage Tests Failed (API Changes):

Example: CTParser needs updates

# CTParser/Project.toml
version = "0.9.0"  # Bump minor (breaking)

[compat]
CTBase = "0.17.0-"
CTModels = "0.11"  # New version

Actions:

1. Adapt code to new APIs
2. Test locally
3. PR with breakage CI
4. Register new version

If Breakage Tests Passed (No API Changes):

Example: OptimalControl still works

# OptimalControl/Project.toml  
version = "0.15.10"  # Bump patch (not breaking)

[compat]
CTBase = "0.16, 0.17.0-"  # Keep wide range
CTModels = "0.10, 0.11"   # Accept both versions
CTDirect = "0.12, 0.13"
# ... etc

Actions:

1. Just update compat ranges
2. No code changes needed
3. Register new version

User impact:

# User on stable OptimalControl 0.15.9
Pkg.add("OptimalControl")
# Gets: CTBase 0.16.0 (still stable preference)

# User installing OptimalControl + CTModels together
Pkg.add(["OptimalControl", "CTModels"])
# Gets: CTBase 0.17.0-beta.1 (to satisfy CTModels)

---

Phase 5: Final Stable Release

Goal: Release CTBase v0.17.0 stable

Step 5.1: Verify Readiness

Check:

• ✅ All packages have versions compatible with CTBase 0.17
• ✅ All breakage tests pass
• ✅ Beta testing period complete (e.g., 2 weeks)
• ✅ No critical issues reported

Step 5.2: Release Stable

File: CTBase/Project.toml

version = "0.17.0"  # ← Remove -beta suffix

Actions:

1. PR to main
2. Merge
3. Register CTBase v0.17.0

Registry state:

CTBase: 0.16.0, 0.17.0-beta.1, 0.17.0 (latest stable)

User impact:

using Pkg
Pkg.update()  # Or new install

# Now gets CTBase v0.17.0 (stable)

Julia's resolver now prefers v0.17.0 over v0.16.0 because:

• Both are stable
• v0.17.0 is higher
• All compat declarations allow it

Step 5.3: (Optional) Tighten Compat

If you want to force users to upgrade:

# CTModels/Project.toml
version = "0.12.0"  # Bump minor (forcing change)

[compat]
CTBase = "0.17"  # ← Removed 0.16

Effect:

• Users who Pkg.update() get the new versions
• Users on old versions stay on old versions
• New installs get latest

Consider:

• Do users need time to migrate?
• Are there good reasons to stay on 0.16?
• Can both versions coexist?

Alternative: Keep both

[compat]
CTBase = "0.16, 0.17"  # Still allow both

This is more user-friendly but means you maintain compatibility.

---

5. How Breakage CI Works Through Migration

5.1 During Beta Phase

Your workflow tests each package in two modes:

Mode 1: Stable Version

- name: test stable
  run: |
    julia --project -e 'using Pkg; Pkg.add(name="${{ matrix.pkg.name }}")'

What happens:

# Package from registry with its declared compat
# Example: OptimalControl v0.15.9 with CTBase = "0.16, 0.17.0-"
# Resolver chooses: CTBase v0.16.0 (stable preferred)
# Uses: CTBase from your PR branch (via override mechanism)

Mode 2: Main Branch

- name: test main
  run: |
    julia --project -e 'using Pkg; Pkg.add(url="...", rev="main")'

What happens:

# Package from GitHub main branch
# Example: OptimalControl@main with CTBase = "0.16, 0.17.0-"
# Resolver chooses: Depends on what main declares
# Uses: CTBase from your PR branch

5.2 Key Insight

The breakage workflow overrides CTBase to use your development version while respecting compat constraints of dependent packages.

This means:

1. If compat is too narrow → test fails with resolution error
2. If compat is wide → test runs with your CTBase
3. If code is incompatible → test fails with runtime error

Why Phase 1 is critical:

• Widens compat before the breaking change
• Ensures breakage tests can run (not just pass/fail)
• Prevents "unable to resolve" errors

---

6. Timeline Example

Real-world timeline for CTBase v0.16 → v0.17 migration:

Week 1: Preparation

• Day 1-2: Create PRs to widen compat on all packages
• Day 3-5: Review, merge, register new versions
• End of Week 1: All packages in registry accept 0.16, 0.17.0-

Week 2: Beta Development

• Day 1-3: Develop breaking changes in CTBase
• Day 4: Run breakage CI, identify issues
• Day 5: Release CTBase v0.17.0-beta.1

Week 3-4: Package Migration

• Week 3: Migrate CTModels, CTParser, CTDirect
• Week 4: Migrate CTFlows, OptimalControl
• Each takes 1-3 days (adapt, test, PR, review, register)

Week 5: Beta Testing

• Community testing with beta versions
• Fix issues if found
• Possibly release v0.17.0-beta.2, beta.3, etc.

Week 6: Stable Release

• Day 1: Release CTBase v0.17.0
• Day 2-7: Monitor for issues
• As needed: Update remaining packages

Total time: ~6 weeks for careful migration

Faster possible: 2-3 weeks if no issues found

---

7. Best Practices and Tips

7.1 Version Numbering

For v0.x packages (pre-1.0):

• Patch bump (0.16.0 → 0.16.1): Bug fixes, no API changes
• Minor bump (0.16.0 → 0.17.0): Breaking changes allowed
• Major stays 0: Until package is considered stable

For v1.x+ packages:

• Patch (1.2.3 → 1.2.4): Bug fixes only
• Minor (1.2.0 → 1.3.0): New features, backward compatible
• Major (1.0.0 → 2.0.0): Breaking changes

7.2 Pre-release Suffixes

Progression:

0.17.0-alpha.1    → Early development, API unstable
0.17.0-alpha.2
0.17.0-beta.1     → Feature complete, testing phase
0.17.0-beta.2
0.17.0-rc.1       → Release candidate, production-ready
0.17.0            → Stable release

For your case: Can skip alpha/rc and just use beta if:

• Changes are well-defined
• Just need integration testing
• Community is small and responsive

7.3 Communication

Announce on:

• GitHub Discussions / Issues
• Julia Discourse (if widely used)
• Package documentation
• CHANGELOG.md

Template announcement:

# CTBase v0.17.0-beta.1 Released

We're preparing CTBase v0.17.0 with the following breaking changes:
- [List breaking changes]

## Testing
To try the beta:
```julia
using Pkg
Pkg.add(name="CTModels", version="0.11.0")  # This pulls in beta

Timeline

• Beta testing: 2 weeks
• Stable release: ~[date]

Feedback

Please report issues at: [link]

### 7.4 Rollback Plan

**If major issues found:**

1. **Don't panic** - users are still on v0.16.0
2. **Fix issues** in new beta version (v0.17.0-beta.2)
3. **Or:** Abandon beta, stay on v0.16
4. **Pre-releases can be yanked** from registry if needed

**Users are protected** because they must opt-in to pre-releases.

---

## 8. FAQ

### Q1: What if a user accidentally installs the beta?

**A:** They would need to explicitly install a package that requires it. For example:
```julia
Pkg.add(name="CTModels", version="0.11.0")

To go back to stable:

Pkg.add(name="CTModels", version="0.10.2")  # Downgrades to stable

Q2: Can different packages use different CTBase versions?

A: No. Julia's Pkg can only have one version of a package in an environment. The resolver finds a single version that satisfies all constraints.

If packages have conflicting requirements (one needs v0.16, another needs v0.17), installation fails. This is why the widening phase is critical.

Q3: What if breakage tests fail after widening compat?

A: This means code changes are needed in the dependent package. The widened compat says "we're compatible" but the code doesn't actually work yet. You need to:

1. Fix the code in the dependent package
2. Then register the fixed version
3. The compat was widened preventively to allow testing

Q4: How do I test locally with the beta?

Option 1: Use registered beta

using Pkg
Pkg.add(name="CTBase", version="0.17.0-beta.1")

Option 2: Use local development

Pkg.develop(path="../CTBase")

Option 3: Use git branch

Pkg.add(url="https://github.com/.../CTBase.jl", rev="feature/v0.17")

Q5: What happens to v0.16 after v0.17 is released?

Registry state:

CTBase: 0.16.0, 0.17.0-beta.1, 0.17.0

All versions remain in registry. Users can pin to v0.16 if needed:

Pkg.add(name="CTBase", version="0.16")

You can (but don't have to) continue bug-fix releases:

CTBase: 0.16.0, 0.16.1 (bug fix), 0.17.0

---

9. Summary Checklist

Phase 1: Preparation (Week 1)

• Widen compat in CTModels
• Widen compat in CTParser
• Widen compat in CTDirect
• Widen compat in CTFlows
• Widen compat in OptimalControl
• Register all new versions

Phase 2: Beta (Week 2)

• Develop breaking changes
• Run breakage CI
• Document breaking changes
• Register CTBase v0.17.0-beta.1

Phase 3: Migrate CTModels (Week 3)

• Adapt CTModels code
• Update CTModels compat
• Test with breakage CI
• Register CTModels new version

Phase 4: Migrate Others (Week 3-4)

• Migrate CTParser (if needed)
• Migrate CTDirect (if needed)
• Migrate CTFlows (if needed)
• Migrate OptimalControl (if needed)

Phase 5: Stable Release (Week 5-6)

• Beta testing period complete
• No critical issues
• Register CTBase v0.17.0
• Announce stable release
• Monitor for issues

---

10. Conclusion

The pre-release strategy with preventive compatibility widening provides a safe and systematic way to migrate breaking changes in Julia packages.

Key advantages:

• ✅ Normal users completely isolated
• ✅ Breakage CI works throughout migration
• ✅ Progressive migration possible
• ✅ Easy rollback if issues found
• ✅ Uses standard Julia/Pkg features
• ✅ No custom tooling required

Requirements:

• Discipline in following the workflow
• Good CI infrastructure (you already have this!)
• Clear communication with users
• Patience during migration period

Your existing breakage CI workflow at CTActions/workflows/breakage.yml is perfectly suited for this approach and will work seamlessly once compat ranges are widened.

Good luck with your migration! 🚀

[ocots]

Practical Workflow for Small Team (3-4 devs, Multiple Repos)

1. Recommended Approach: Simplified Polyrepo with Local Development

For a small team (3-4 developers) with a few packages (5-10), I recommend:

Core Strategy:

• Keep separate repositories (polyrepo)
• Use Pkg.develop() for local development
• Minimal version constraints during development
• Simple, manual coordination (no complex CI)
• Register versions only when truly stable

Why this approach?

• ✅ Minimal setup and maintenance
• ✅ Leverages Julia's excellent develop mode
• ✅ No complex build systems needed
• ✅ Easy for everyone to understand
• ✅ Flexible for experimentation
• ✅ Scales well from 3 to ~10 packages

---

2. Repository Structure

2.1 Keep Current Structure

GitHub Organization: control-toolbox/
├── CTBase.jl/
├── CTModels.jl/
├── CTParser.jl/
├── CTDirect.jl/
├── CTFlows.jl/
└── OptimalControl.jl/

No changes needed! Polyrepo is fine for small teams.

2.2 Local Development Structure

Each developer has a local folder:

~/projects/control-toolbox/
├── CTBase/
├── CTModels/
├── CTParser/
├── CTDirect/
├── CTFlows/
└── OptimalControl/

All repos cloned side-by-side in one parent folder.

---

3. Daily Development Workflow

3.1 Initial Setup (Once per Developer)

Step 1: Clone all repositories

cd ~/projects
mkdir control-toolbox
cd control-toolbox

git clone https://github.com/control-toolbox/CTBase.jl.git CTBase
git clone https://github.com/control-toolbox/CTModels.jl.git CTModels
git clone https://github.com/control-toolbox/CTParser.jl.git CTParser
git clone https://github.com/control-toolbox/CTDirect.jl.git CTDirect
git clone https://github.com/control-toolbox/CTFlows.jl.git CTFlows
git clone https://github.com/control-toolbox/OptimalControl.jl.git OptimalControl

Step 2: Create a development environment

cd OptimalControl
julia --project=@.

using Pkg

# Develop all local packages
Pkg.develop(path="../CTBase")
Pkg.develop(path="../CTModels")
Pkg.develop(path="../CTParser")
Pkg.develop(path="../CTDirect")
Pkg.develop(path="../CTFlows")

# This ignores version constraints completely!
# Always uses your local code

Step 3: Create a startup script (optional but recommended)

~/projects/control-toolbox/dev-setup.jl:

using Pkg

packages = [
    "../CTBase",
    "../CTModels", 
    "../CTParser",
    "../CTDirect",
    "../CTFlows"
]

println("Setting up development environment...")
for pkg in packages
    println("  Developing: $pkg")
    Pkg.develop(path=pkg)
end

println("✓ Development environment ready!")
println("All packages use local versions.")

Usage:

julia> include("dev-setup.jl")

3.2 Working on Changes

Scenario: You want to change CTBase

cd ~/projects/control-toolbox/CTBase
git checkout -b feature/new-api
# Make your changes

Test in isolation:

cd CTBase
julia --project
using Pkg
Pkg.test()  # Run CTBase tests

Test with dependents:

cd ../OptimalControl
julia --project
using Pkg
Pkg.test()  # This uses your local CTBase automatically!

No need to:

• ❌ Change version numbers
• ❌ Update compat declarations
• ❌ Register anything
• ❌ Wait for CI

Everything is instant and local!

3.3 Checking What's Developed

using Pkg
Pkg.status()

Output:

Status `~/projects/control-toolbox/OptimalControl/Project.toml`
  [1234] CTBase v0.16.0 `../CTBase` (dev)
  [5678] CTModels v0.10.2 `../CTModels` (dev)
  ...

The (dev) marker shows you're using local versions.

3.4 Switching Back to Registry Versions

using Pkg
Pkg.free("CTBase")  # Use registry version instead

Or free everything:

for pkg in ["CTBase", "CTModels", "CTParser", "CTDirect", "CTFlows"]
    Pkg.free(pkg)
end

---

4. Version Management (Simplified)

4.1 Development Phase: No Version Bumps

While actively developing:

• Don't bump versions
• Don't worry about compat
• Work freely across packages
• Commit to feature branches

Example workflow:

# Day 1: Feature in CTBase
cd CTBase
git checkout -b feature/improve-api
# ... make changes ...
git commit -m "Improve API"

# Day 2: Adapt CTModels
cd ../CTModels  
git checkout -b feature/use-new-ctbase-api
# ... adapt to new CTBase ...
git commit -m "Use new CTBase API"

# Day 3: Update OptimalControl
cd ../OptimalControl
# ... test everything together ...
# Everything works? Great!

No version changes, no registry, no waiting!

4.2 Release Phase: When You're Ready

Only register when:

• Feature is complete and tested
• You want external users to access it
• You're ready to commit to the API
• You need a stable reference point

Process:

1. Merge feature branches to main
2. Bump version numbers in Project.toml
3. Update compat if needed
4. Register one by one, respecting dependency order

Order matters:

1. CTBase        (no dependencies)
2. CTModels      (depends on CTBase)
3. CTParser      (depends on CTBase, CTModels)
4. CTDirect      (depends on CTBase, CTModels)
5. CTFlows       (depends on CTBase, CTModels)
6. OptimalControl (depends on everything)

4.3 Very Relaxed Compat Strategy

For a small team, use wide compat ranges:

# CTModels/Project.toml
[compat]
CTBase = "0.16"   # Accepts all 0.16.x

# Or even wider for development packages:
CTBase = "0.16, 0.17, 0.18"  # Very permissive

Philosophy:

• You control all packages
• You test them together
• Wide ranges reduce friction
• Tighten only if needed for external users

---

5. Handling Breaking Changes (Simplified)

5.1 Small Team Advantage

You don't need the complex pre-release workflow!

Why?

• You test everything together locally
• You can coordinate in a Slack/Discord channel
• You can fix issues immediately
• No external users to worry about (yet)

5.2 Simple Breaking Change Process

Step 1: Announce in team chat

@team: Working on CTBase breaking changes today.
Will update all packages. Don't merge anything until I'm done! 🚧

Step 2: Make changes across all packages

# Work in all repos simultaneously
cd CTBase
# ... breaking changes ...

cd ../CTModels
# ... adapt ...

cd ../CTParser
# ... adapt ...

# etc.

Step 3: Test everything locally

cd OptimalControl
julia --project
using Pkg
Pkg.test()  # Tests with all your local changes

Step 4: When all works, merge everything

# Create PRs for all packages
cd CTBase && git push
cd ../CTModels && git push
cd ../CTParser && git push
# ... etc

Step 5: Merge in order (dependencies first)

1. Merge CTBase PR
2. Merge CTModels PR
3. Merge CTParser, CTDirect, CTFlows PRs
4. Merge OptimalControl PR

Step 6: Register new versions

1. Register CTBase v0.17.0
2. Wait for registration to complete
3. Register CTModels v0.11.0
4. Register others
5. Register OptimalControl last

Timeline: Can be done in a few hours to a day (not weeks!)

5.3 If You Need More Safety

Optional: Use feature branches

# Everyone works on a shared feature branch
cd CTBase
git checkout -b epic/v0.17-migration
git push -u origin epic/v0.17-migration

cd ../CTModels
git checkout -b epic/v0.17-migration
# ... etc for all repos

Then:

• Everyone develops on these branches
• Test together
• When ready, merge all to main simultaneously
• Register new versions

---

6. Minimal CI Setup

6.1 What You Actually Need

For a small team, keep CI simple:

Per repository:

# .github/workflows/ci.yml
name: CI
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: julia-actions/setup-julia@v2
        with:
          version: '1.10'
      - uses: julia-actions/julia-buildpkg@v1
      - uses: julia-actions/julia-runtest@v1

That's it! Just test the package in isolation.

6.2 Skip Complex Breakage Testing

Why?

• You test locally with Pkg.develop()
• You coordinate directly
• Breakage CI is useful for large projects with many external dependents
• Your external users are few (or none yet)

When to add it:

• Package becomes popular (100+ GitHub stars)
• Many external packages depend on you
• You can't test everything locally anymore

For now: Don't build what you don't need!

---

7. Team Coordination

7.1 Communication Tools

Minimal setup:

• GitHub Issues/Discussions - for features and bugs
• Slack/Discord channel - for daily coordination
• Weekly sync call (30 min) - if async isn't enough

Key practices:

• Announce when working on breaking changes
• Ask before merging large changes
• Quick review cycle (hours, not days)
• Trust each other

7.2 Branch Strategy

Simple GitHub Flow:

main (always deployable)
  ├── feature/improve-api (your work)
  ├── feature/add-solver (teammate's work)
  └── bugfix/edge-case (another teammate)

Rules:

• Feature branches off main
• PR to merge to main
• 1-2 approvals if you want (or self-merge if trusted)
• Delete branch after merge

No need for:

• ❌ develop branch
• ❌ release branches
• ❌ gitflow complexity

7.3 Documentation

Keep a simple CHANGELOG.md in each repo:

# Changelog

## Unreleased
- Improved API for X
- Fixed bug in Y

## [0.17.0] - 2025-01-20
### Breaking
- Changed function signature for `solve()`
- Removed deprecated `old_function()`

### Added
- New solver algorithm

## [0.16.0] - 2025-01-10
...

Update as you go, not before release.

---

8. Scaling Strategy

8.1 When You're Still 3-4 People

Current approach works great:

• Develop locally
• Coordinate manually
• Register occasionally
• Minimal CI

8.2 When You Grow to 5-10 People

Add:

• ✅ More structured PRs (require reviews)
• ✅ Better documentation
• ✅ More frequent releases
• ✅ Possibly add breakage CI
• ❌ Still no need for monorepo

8.3 When You Grow to 10+ People

Consider:

• Workspace-based monorepo
• More automated testing
• Dedicated CI/CD person
• Stricter semver adherence

But that's future you's problem!

---

9. Common Scenarios

9.1 "I Need to Test a Feature Across Packages"

# In OptimalControl (or any test package)
using Pkg

# Develop all packages you're changing
Pkg.develop(path="../CTBase")
Pkg.develop(path="../CTModels")

# Run tests
Pkg.test()

# Or test manually
using OptimalControl
# ... your test code ...

9.2 "Someone Else Changed CTBase, I Need to Update"

cd ~/projects/control-toolbox/CTBase
git pull origin main

# Your local OptimalControl automatically uses the new code!
cd ../OptimalControl
julia --project -e 'using Pkg; Pkg.test()'

9.3 "I Want to Use Registry Version for One Package"

using Pkg

# Free specific package
Pkg.free("CTBase")

# Now CTBase comes from registry
# Others still use local versions

9.4 "New Team Member Onboarding"

Give them:

1. Clone script (or one-liner)
2. The dev-setup.jl script
3. 5 minute walkthrough

Total time: 30 minutes including downloads.

9.5 "I Broke Everything Locally"

using Pkg

# Nuclear option: reset everything
Pkg.free("CTBase")
Pkg.free("CTModels")
# ... etc

# Or delete Manifest.toml and rebuild
rm("Manifest.toml")
Pkg.instantiate()

---

10. What NOT to Do (Don't Overcomplicate!)

❌ Don't Set Up a Monorepo

• Unnecessary complexity for 3-4 people
• Harder for external contributors
• Lose flexibility of separate repos

❌ Don't Build Complex CI

• Breakage testing across packages? Skip it.
• Matrix testing multiple Julia versions? Maybe just 1.10.
• Deploy docs on every commit? Do it on release.

❌ Don't Obsess Over Versions

• Don't bump versions daily
• Don't create releases for every fix
• Bundle changes into meaningful releases

❌ Don't Use Pre-releases (Yet)

• Only needed for packages with many external users
• Adds complexity you don't need
• Just merge when ready

❌ Don't Write Extensive Docs (Yet)

• Code examples in README
• Docstrings on functions
• That's enough until you have users

---

11. The "Lazy Developer" Workflow (Recommended!)

This is what I'd actually do with 3-4 people:

Daily Work

1. Start Julia with all packages developed
2. Edit code in any package
3. Test immediately (no registration needed)
4. Commit when something works
5. Push when ready to share

Weekly or Bi-weekly

1. Sync with team - "What's ready to release?"
2. Merge all feature branches
3. Bump versions together
4. Register in one batch
5. Continue developing

For Breaking Changes

1. Announce in team chat
2. Work through all repos in one session
3. Test locally before pushing
4. Push + merge + register same day

Total overhead: Maybe 1-2 hours per week on coordination.

---

12. Concrete Example: Real Breaking Change

Scenario: Need to change CTBase API

Monday Morning (2 hours)

9:00  - Team sync: "Working on CTBase API change today"
9:15  - cd CTBase && git checkout -b feature/new-api
9:30  - Change API, update tests
10:00 - cd ../CTModels && adapt code
10:30 - cd ../CTParser && adapt code
10:45 - cd ../OptimalControl && test everything
11:00 - Everything works? Great! Push all branches.

Monday Afternoon (1 hour)

14:00 - Create PRs for all repos
14:15 - Quick review (or self-merge if solo)
14:30 - Merge everything to main
14:45 - Register: CTBase v0.17.0
15:00 - Register: CTModels v0.11.0 (after CTBase is registered)
15:15 - Register: Others
15:30 - Done! ✅

Total time: 3 hours, breaking change deployed.

Compare to complex workflow: multiple weeks! 😱

---

13. Setup Checklist

One-Time Setup (30 minutes)

• Clone all repositories to local folder
• Create dev-setup.jl script
• Run dev-setup.jl in main project
• Test that everything works
• Document process in README

Per-Developer Setup (30 minutes)

• Clone repositories
• Run setup script
• Join team chat
• Read workflow doc

Per-Release (1-2 hours)

• Merge feature branches
• Bump versions
• Update CHANGELOGs
• Register in dependency order
• Tag releases on GitHub

---

14. Why This Works for Small Teams

✅ Advantages

1. Fast iteration - no waiting for CI or registrations
2. Simple - everyone understands it
3. Flexible - change approach as needed
4. Low maintenance - no complex systems to maintain
5. Julia-native - uses Pkg.develop() as intended
6. Scalable - can grow with team

⚠️ Limitations

1. Requires discipline - team must coordinate
2. Local only - can't test "as user would install"
3. Manual - no automation safety net
4. Not for open source - assumes you control all repos

But for 3-4 developers? Perfect! ✨

---

15. One-Line Summary

Use Pkg.develop() for everything during development, coordinate breaking changes in team chat, register infrequently, keep CI minimal.

---

16. Getting Started Today

Literally right now, you can:

# 1. Create local dev folder
mkdir -p ~/projects/control-toolbox && cd ~/projects/control-toolbox

# 2. Clone everything
for repo in CTBase CTModels CTParser CTDirect CTFlows OptimalControl; do
  git clone https://github.com/control-toolbox/${repo}.jl.git ${repo}
done

# 3. Set up development
cd OptimalControl
julia --project -e 'using Pkg; 
  Pkg.develop(path="../CTBase");
  Pkg.develop(path="../CTModels");
  Pkg.develop(path="../CTParser");
  Pkg.develop(path="../CTDirect");
  Pkg.develop(path="../CTFlows");
  Pkg.test()'

# 4. Start working!

Total time: 10 minutes. 🚀

Now you have a fully functional development environment with zero complex tooling!

---

17. Final Recommendation

For your team of 3-4 developers with ~6 packages:

1. ✅ Keep polyrepo structure
2. ✅ Use Pkg.develop() for local work
3. ✅ Coordinate breaking changes manually
4. ✅ Register versions infrequently (monthly?)
5. ✅ Keep CI minimal (just run tests)
6. ✅ Use wide compat ranges
7. ✅ Trust each other

DON'T:

• ❌ Set up monorepo
• ❌ Build complex CI
• ❌ Use pre-release workflow (yet)
• ❌ Obsess over versions

Save the complex stuff for when you have 20+ packages and 50+ developers.

For now: Keep it simple, keep it fast, keep coding! 🎉

[jbcaillau]

nice @ocots !!! so either pre-release, or dev locally on the full hierarchy, right?

@amontoison any thought on this?

[amontoison]

I think it is a bit overkill what is suggested and will probably not work in Julia.
You can't dev locally except if the compat entries are compatible.
Don't forget that you have a very small ecosystem.

CI will take care to open a PR to update all the Project.toml when a dependency has a breaking release.
Just not bump the release number until the last moment should be enough.

[jbcaillau]

you have overkilled me @amontoison 🥲

[ocots]

See new repo https://github.com/control-toolbox/DevelopmentGuide.

[jbcaillau]

principles are clear; implementing that without a tool (an agent...) is HOT stuff. we are almost immediately in the cascading more complicated case, even with our small arch.

[jbcaillau]

@ocots

• in the cascading case, it is important to think of phase 4b (make a beta available for the full system)
• we have a use case right now with current updates in CTBase, CTModels, CTParser 👀

[jbcaillau]

@ocots although it does not look so standard in Julia, seems good practice here to use the local reg you revived 👍🏽 https://github.com/control-toolbox/DevelopmentGuide

[amontoison]

Note that the general registry doesn't accept a version number that is different than x.y.z (except for JLL where we can add +i at the end).
Be careful with LLM, it says a lot of wrong things...