| name | config-migration |
| description | Resolve BC/RL config migration conflicts and add new migrations by bumping versions, updating migrate_to_v* methods/maps, regenerating sample snapshots, and validating tests. |
Config Migration
Use this skill when:
- a merge/rebase causes migration version conflicts in BC or RL, or
- you changed config schema and need to add a new migration method/version.
Goal
When two branches both add migration version vN, do not force-merge into the same vN.
Resolve by:
- Bumping your branch to
vN+1
- Moving your migration logic from
migrate_to_vN to migrate_to_vN_plus_1
- Updating migration dict mapping to the new version
- Accepting incoming existing sample snapshot(s)
- Generating a new sample snapshot for the new version
- Updating reference configs and migration tests
Paths
BC
- Version source of truth:
wayve/ai/si/config.py (bc_version.version_number)
- Migration file:
wayve/ai/si/configs/versioning/bc_migrations.py- function map:
BC_CONFIG_MIGRATION_FUNCTIONS
- Sample snapshots:
wayve/ai/si/test/data/sample_configs/bc/v*.yaml
- Reference configs:
wayve/ai/si/test/test_config_inputs/reference_bc.yamlwayve/ai/si/test/test_config_inputs/reference_bc_alpha2.yaml
- Migration tests:
wayve/ai/si/test/configs/test_bc_migrations.py
RL
- Version source of truth:
wayve/ai/si/configs/store/offline_rl.py (rl_config_version.version_number)
- Migration file:
wayve/ai/si/configs/versioning/rl_migrations.py- function map:
RL_CONFIG_MIGRATION_FUNCTIONS
- Sample snapshots:
wayve/ai/si/test/data/sample_configs/rl/v*.yaml
- Reference configs:
wayve/ai/si/test/test_config_inputs/reference_rl.yamlwayve/ai/si/test/test_config_inputs/reference_rl_alpha2.yaml
- Migration tests:
wayve/ai/si/test/configs/test_rl_migrations.py
Conflict Resolution Workflow
1) Determine incoming highest version
Check current version in source-of-truth file and migration map.
2) Bump version number
- BC: bump
bc_version.version_number in wayve/ai/si/config.py
- RL: bump
rl_config_version.version_number in wayve/ai/si/configs/store/offline_rl.py
3) Renumber migration function
If your logic was in migrate_to_vN and incoming already uses vN:
- Keep incoming
migrate_to_vN
- Move your logic to
migrate_to_vN_plus_1
- Update mapping dict (
...MIGRATION_FUNCTIONS) to point new version to your new function
4) Accept incoming sample config for existing versions
For conflicted existing snapshots (e.g. vN.yaml): accept incoming.
Rule: do not rewrite historical incoming snapshots during conflict resolution.
5) Generate new sample config for your new version
- BC:
bazel run //wayve/ai/si/scripts:dump_sample_cfg_for_migration_checks -- --training_stage=bc
- RL:
bazel run //wayve/ai/si/scripts:dump_sample_cfg_for_migration_checks -- --training_stage=rl
This writes:
wayve/ai/si/test/data/sample_configs/bc/v<new>.yaml orwayve/ai/si/test/data/sample_configs/rl/v<new>.yaml
6) Update reference config version fields
Update only top-level stage version field to the new version:
- BC refs:
reference_bc.yamlreference_bc_alpha2.yaml
- RL refs:
reference_rl.yamlreference_rl_alpha2.yaml
7) Update migration tests if function names changed
Important BC vs RL difference:
- BC tests mostly validate through
migrate_bc_config_to_latest; function-specific renumber changes are rare.
- RL tests may import specific functions (e.g.
migrate_to_v20) in test_rl_migrations.py; if you renumber, update imports/test names accordingly.
Validation
Run targeted validation first:
- BC:
bazel test //wayve/ai/si:test_config_py_test --test_output=errors --test_arg='-k=bc_migrations'
- RL:
bazel test //wayve/ai/si:test_config_py_test --test_output=errors --test_arg='-k=rl_migrations'
Then full config checks:
bazel test //wayve/ai/si:test_config --test_output=errors
New Migration Workflow (No Existing migrate_to_v* Yet)
Use this when you made a config-schema change and need to add a fresh migration.
1) Pick the next version
- Read current version from source-of-truth:
- BC:
wayve/ai/si/config.py (bc_version.version_number)
- RL:
wayve/ai/si/configs/store/offline_rl.py (rl_config_version.version_number)
- New version is
current + 1.
2) Bump version source of truth
- BC: update
bc_version.version_number
- RL: update
rl_config_version.version_number
3) Add a new migration method
- BC file:
wayve/ai/si/configs/versioning/bc_migrations.py
- RL file:
wayve/ai/si/configs/versioning/rl_migrations.py
Add:
def migrate_to_v<new>(config: <CfgType>) -> <CfgType>:- Implement schema transition for your new fields/renames/removals.
- Return migrated config.
Template:
def migrate_to_v23(config: RLCfg) -> RLCfg:
if config.some_block.new_field is None:
config.some_block.new_field = "default_value"
return config
4) Register it in migration map
- BC: add entry to
BC_CONFIG_MIGRATION_FUNCTIONS
- RL: add entry to
RL_CONFIG_MIGRATION_FUNCTIONS
Example:
RL_CONFIG_MIGRATION_FUNCTIONS = {
...
23: migrate_to_v23,
}
5) Regenerate sample snapshot for new version
- BC:
bazel run //wayve/ai/si/scripts:dump_sample_cfg_for_migration_checks -- --training_stage=bc
- RL:
bazel run //wayve/ai/si/scripts:dump_sample_cfg_for_migration_checks -- --training_stage=rl
6) Update reference configs
Bump top-level version field in:
- BC:
reference_bc.yaml, reference_bc_alpha2.yaml
- RL:
reference_rl.yaml, reference_rl_alpha2.yaml
7) Update migration tests
- If tests import/version-pin specific methods (common in RL), update imports and expected version/method references.
- Run stage-specific migration tests, then full config tests.
Common Mistakes
- Keeping your new logic in a version number already claimed by incoming.
- Modifying old incoming snapshot (
vN.yaml) instead of adding vN+1.yaml.
- Forgetting to update reference config version fields.
- For RL: forgetting to update function-specific imports/tests in
test_rl_migrations.py after renumbering.
- Adding new config fields but forgetting to create/register a new
migrate_to_v* method.
Quick Checklist
