Upgrading
A Puerto project has two things that change with Puerto: the code it generated, which is yours, and the runtime crates it depends on, which are not. They upgrade differently.
Patches arrive with cargo update
Section titled “Patches arrive with cargo update”The runtime crates (puerto-nucleo, puerto-web, puerto-sqlx and the rest) are released in
lockstep with the CLI, and a project asks for the minor that generated it:
[workspace.dependencies]puerto-nucleo = "0.21"puerto-web = "0.21"A fix in a patch release (0.21.1) reaches the project with cargo update. Nothing to
regenerate. That is the reason the runtime exists
(ADR-0017).
A new minor is a deliberate step
Section titled “A new minor is a deliberate step”While Puerto is 0.x, a minor version can change what the generator writes and the runtime’s
API. Every one of those changes is listed under Breaking in the
changelog, with a Migration Guide when there are projects to migrate.
-
Upgrade the CLI.
cargo install puerto --locked --force -
Ask the project.
puerto validarIt warns for each runtime crate on another minor than the CLI.
-
Read the migration guide of every minor you cross, and apply it. Bump the crates in the root
Cargo.toml, then:puerto generar bootstrap # regenerate what Puerto ownsmake test && make lint && make format
0.21 has no migration guide
Section titled “0.21 has no migration guide”0.21 changed the shape of every generated project: one crate per context and layer under
contextos/, nucleo/ and presentacion/
(ADR-0023), and everything generated,
puerto.toml and the CLI in Spanish
(ADR-0024). The runtime crates
puerto-core, puerto-events and puerto-mail became puerto-nucleo, puerto-eventos and
puerto-correo. It ships without a migration guide, because no generated projects existed to
migrate. A project generated by 0.20 keeps working on the 0.20 crates, which stay on crates.io;
to move it to 0.21, generate a new project with puerto nuevo and bring your code across.
Migration guides are written for agents too
Section titled “Migration guides are written for agents too”When a release changes generated code, its guide ends with a paragraph meant to be pasted into your coding agent as is. From 0.14, for example:
Upgrade this Puerto project from 0.13 to 0.14. In the root
Cargo.tomladd[workspace.dependencies]withpuerto-core = "0.14",puerto-web = "0.14"and, ifinfrastructureuses sqlx,puerto-sqlx = "0.14"; […] then runpuerto generate bootstrap,puerto validateandmake test.
The agent does the mechanical part, and the tests tell it when it is done.