Skip to content

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.

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:

Cargo.toml
[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).

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.

  1. Upgrade the CLI.

    cargo install puerto --locked --force
  2. Ask the project.

    puerto validar

    It warns for each runtime crate on another minor than the CLI.

  3. 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 owns
    make test && make lint && make format

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.toml add [workspace.dependencies] with puerto-core = "0.14", puerto-web = "0.14" and, if infrastructure uses sqlx, puerto-sqlx = "0.14"; […] then run puerto generate bootstrap, puerto validate and make test.

The agent does the mechanical part, and the tests tell it when it is done.