# Mojo 1.0 Library Migration Wave Plan # Problem statement Mojo has reached the 1.0 release phase, and the DataBooth `mojo-*` libraries need a coordinated migration from mixed pre-1.0 and beta-era assumptions to a stable, repeatable Mojo 1.0 baseline. The migration should also produce a progressive public narrative capturing gotchas, lessons, and release-engineering decisions. \## Current state `mojo-toml` is the furthest along and already uses a workspace manifest plus a 1.0 beta pin (`pixi.toml:1`, `pixi.toml:68`) with an existing migration write-up (`docs/MOJO_1_0_MIGRATION_BLOG.md:2`, `docs/MOJO_1_0_MIGRATION_BLOG.md:4`). Other target repos still show pre-1.0 posture in one or more places: \* `../mojo-asciichart/pixi.toml:1` and `../mojo-asciichart/pixi.toml:47` \* `../mojo-dotenv/pixi.toml:1` and `../mojo-dotenv/pixi.toml:58` \* `../mojo-ini/pixi.toml:1` and `../mojo-ini/pixi.toml:49` \* `../mojo-yaml/pixi.toml:1` and `../mojo-yaml/pixi.toml:46` Packaging compiler pins remain at `=0.26.1` in several repos: \* `../mojo-asciichart/packaging/recipe.yaml:3` \* `../mojo-dotenv/packaging/recipe.yaml:3` \* `../mojo-ini/packaging/recipe.yaml:3` \* `../mojo-yaml/packaging/recipe.yaml:3` `mojo-benchsuite` currently uses a nightly channel and has a placeholder test task (`../mojo-benchsuite/pixi.toml:3`, `../mojo-benchsuite/pixi.toml:40`), so its migration needs both compatibility and release-hardening work. \## Proposed changes \### 1) Establish canonical Mojo 1.0 policy in `mojo-toml` first Use `mojo-toml` as the pilot repo to define canonical policy for: \* dependency pinning strategy for Mojo 1.0 (runtime + packaging/compiler constraints) \* channels and manifest schema conventions \* recipe pin and compatibility policy \* CI matrix and release validation expectations Any unresolved ambiguity (pin granularity, channel order, lockfile policy) is decided once in `mojo-toml`, then reused in all sibling repos. \### 2) Create a shared migration playbook before editing sibling repos After pilot validation in `mojo-toml`, codify one playbook for every repo: \* manifest normalization (`[project]`/`[workspace]`, channels, dependency policy) \* recipe/compiler pin migration and package smoke-test rules \* source/test syntax and stdlib compatibility updates required by 1.0 \* CI/workflow parity requirements (tests, recipe validation, package build) \* post-migration verification commands and acceptance checks This avoids six one-off migrations and keeps release behavior consistent. \### 2a) Pilot outcomes from `mojo-toml` (playbook v1) The pilot uncovered one hard compatibility blocker and several mechanical updates that should now be applied proactively in sibling repos. Core reusable pattern: \* **Recursive value model fix**: Mojo 1.0 rejects direct recursive container fields such as `List[Self]`/`Dict[String, Self]` with Deinitable errors. Use boxed recursive storage (`Pointer[..., MutUntrackedOrigin]`) plus explicit deep-copy and `__deinit__` cleanup for owned boxed values. Mechanical language/std changes to apply early: \* replace legacy `fn` declarations with `def` \* move test imports from `testing` to `std.testing` \* prefer `std.` import paths (for example `std.math`) \* replace `len(String)` usage with explicit length APIs (`byte_length()`, `len(codepoints())`, or `len(graphemes())` as appropriate) Validation gate proven in pilot: \* `pixi lock` \* `pixi run mojo-version` \* `pixi run test-all` \* `pixi run build-package` If these pass in each repo, the migration is functionally complete for that repo's baseline. \### 3) Roll out to remaining repos in controlled waves Apply the playbook in two rollout waves: \* Wave A: `../mojo-asciichart`, `../mojo-dotenv`, `../mojo-ini`, `../mojo-yaml` \* Wave B: `../mojo-benchsuite` (includes extra hardening because of current nightly/testing posture) Each repo migration ends with local validation + CI alignment before moving on. \### 4) Keep release engineering in scope Migration is complete per repo only when source compatibility and release mechanics both pass: \* tests/examples/benchmarks (repo-appropriate) \* recipe validation \* package build and smoke install checks \* docs alignment for install and release workflows \## Progressive blog capture strategy Run a parallel documentation stream from day one: \* Keep `docs/MOJO_1_0_MIGRATION_BLOG.md` in `mojo-toml` as the canonical living narrative draft. \* Add structured per-repo migration notes ("what changed / what broke / fix pattern / validation evidence"). \* After each repo wave, fold validated lessons into the central draft with concrete gotchas and reusable patterns. \* Publish once all six repos are migrated and validated, with an appendix of practical interop/tooling pitfalls and mitigations. \## Risk management Primary risks are hidden API/stdlib incompatibilities, packaging drift, and release workflow regressions. Mitigation approach: \* pilot-first policy in `mojo-toml` \* strict reuse of one migration playbook \* verification gates at repo boundaries \* progressive documentation so repeated failures become explicit reusable fixes \## Success criteria Success means all six repos are on a coherent Mojo 1.0 baseline with aligned manifests, recipes, and CI/release workflows, and a publication-ready migration article exists documenting practical gotchas and lessons from the full wave.