Migration Guide

Relevant source files

The following files were used as context for generating this wiki page:

• CHANGELOG.md
• src/config.rs
• src/init.rs
• src/executor.rs
• README.md
• src/isolation.rs

The version 0.3.0 release of cargo-cooldown introduced significant architectural changes and breaking configuration updates. This guide outlines the transition from legacy versions to the new system, which features multi-registry support, improved release-time resolution, and a centralized configuration format.

The primary shift involves moving from a fragmented configuration model to a unified cooldown.toml file, alongside the introduction of an interactive initialization wizard.

Sources: CHANGELOG.md:15-17, CHANGELOG.md:46-60

Configuration System Overhaul

Configuration has been consolidated into a single cooldown.toml file. Previously, allow rules and registry settings might have existed in separate layers; these are now integrated into one schema.

New Configuration Schema

The cooldown.toml file now supports a structured allow section for rules and global settings for enforcement and baseline behavior.

Key	Type	Default	Description
cooldown_minutes	u64	0	Minimum age of a release to be accepted.
enforcement	String	strict	Policy for fresh versions (strict, cargo_compatible, off).
cargo_compatible_accept	String	prompt	Policy for accepting fresh versions (prompt, auto).
lockfile_baseline	String	floor	Use initial Cargo.lock as a floor (floor, ignore).
skip_registries	Vec	[]	List of registry names or URLs to skip.

Sources: src/config.rs:105-119, src/config.rs:158-169, README.md:58-65

Precedence Logic

Configuration is now loaded in a strict hierarchy, allowing for global defaults with specific overrides for workspace members.

The diagram shows the loading order where environment variables have the highest priority, overriding any file-based settings.

Sources: src/config.rs:88-96, README.md:67-72

Enforcement Policies

Version 0.3.0 introduced explicit enforcement modes to control how the system reacts when a fresh version cannot be cooled due to dependency constraints.

Policy Comparison

The transition requires selecting an enforcement level that matches the project's risk tolerance.

• Strict: (Default) Fails the command and restores the original lockfile if any fresh versions remain that cannot be cooled.
• CargoCompatible: Allows the command to proceed but issues warnings. By default, it prompts the user for confirmation unless configured to auto.
• Off: Bypasses all cooldown checks.

Sources: src/config.rs:18-30, README.md:83-93, src/executor.rs:253-265

Interactive Prompts

Under cargo_compatible enforcement, the system now requires user interaction to accept fresh versions. Users migrating automated pipelines should set COOLDOWN_CARGO_COMPATIBLE_ACCEPT=auto.

Sources: src/config.rs:43-52, src/executor.rs:310-318

Workspace Isolation and Safety

A major internal change is the use of temporary workspaces for lockfile resolution. cargo-cooldown now prevents race conditions by holding the real Cargo.lock with a sentinel file.

This flow ensures the project remains in a valid state even if the cooling process is interrupted.

Sources: src/executor.rs:65-71, src/isolation.rs:37-60, src/isolation.rs:134-160

Migration Steps

To migrate a project to the latest version, follow these steps:

1. Install the new version: Ensure the latest binary is installed via cargo install cargo-cooldown.
2. Initialize the configuration: Run cargo cooldown init in the project root. This wizard will detect the project type (crate or workspace) and guide the creation of the cooldown.toml.
3. Consolidate Allow Rules: If you had previous allow rules, move them into the [[allow.package]] or [[allow.exact]] sections of the new cooldown.toml.
4. Define Registries: If using private registries, add them to the skip_registries list if you do not want them inspected.
5. Update CI/CD: If running in non-interactive environments, export COOLDOWN_CARGO_COMPATIBLE_ACCEPT=auto.

Sources: src/init.rs:40-62, src/init.rs:228-234, CHANGELOG.md:46-60, README.md:104-122

Summary of Technical Changes

Feature	Legacy Behavior	v0.3.0+ Behavior
Lockfile Logic	Direct mutation	Isolated temporary workspace resolution
Registry Metadata	Separate routing layer	Follows Cargo's effective config
Timestamp Source	Primary HTTP API	Index-first (pubtime) with HTTP fallback
Safety	Manual backup	Automatic sentinel "hold" and backup
Workspace Support	Global cooling	Member-specific scoped cooling

Sources: CHANGELOG.md:65-90, src/executor.rs:105-115, src/isolation.rs:172-185