Release & Versioning

Rust usa SemVer em Cargo.toml. Aplicações marcam releases no git; bibliotecas publicam no crates.io com entradas de changelog e promessas de estabilidade de API.

Receita

# Instalar helper de release
cargo install cargo-release
 
# Incrementar versão patch, atualizar lock, marcar
cargo release patch --execute

# Cargo.toml
[package]
name = "my-lib"
version = "0.3.2"
rust-version = "1.97"

Quando usar isto:

Publicando crates de workspace
Distribuindo ferramentas CLI com saída --version
Coordenando mudanças de API que quebram compatibilidade entre dependentes

Exemplo em Funcionamento

# Serviço binário: tag git direciona o deploy
git tag v2.1.0
git push origin v2.1.0
# CI constrói o container ghcr.io/acme/api:2.1.0

// Expor a versão na CLI
const VERSION: &str = env!("CARGO_PKG_VERSION");
 
fn main() {
    println!("my-cli {VERSION}");
}

O que isto demonstra:

CARGO_PKG_VERSION embutido no tempo de compilação da versão
Tags Git alinhadas com tags de container
cargo-release automatiza o manifest + tag git

Mergulho Profundo

Regras SemVer para APIs Rust

Mudança	Incremento
Quebra de trait/struct público	Major (1.0+) ou minor (0.x)
Nova API aditiva	Minor
Correção de bug, interna	Patch

#[non_exhaustive] e traits selados suavizam a evolução para bibliotecas.

Changelogs

Mantenha CHANGELOG.md no formato Keep a Changelog. Linke seções para URLs de comparação do GitHub.

Releases de Workspace

Libere crates internos na ordem de dependência ou use release-plz para incrementos coordenados.

Armadilhas

Mudança que quebra em patch - quebra downstream. Correção: CI com cargo semver-checks.
Esqueceu de publicar todos os membros do workspace - descompasso de versão. Correção: checklist de release por crate.
Crate 0.x tratado como estável - SemVer permite quebras em minor. Correção: documentar a política de estabilidade.
Tag Git sem atualização do lockfile - builds de tag não reproduzíveis. Correção: commitar lock com a tag.
Crate yanked deixado no lock - cargo build falha. Correção: cargo update -p crate prontamente.

Alternativas

Alternativa	Usar Quando	Não Usar Quando
`release-plz`	Workspaces com múltiplos crates	Repositório de binário único
Incremento manual de versão	Controle total	Releases frequentes
Versionamento por calendário	Apenas deploy SaaS	Bibliotecas publicadas

FAQs

Quando atingir 1.0?

Quando o contrato da API pública for estável e mudanças que quebram compatibilidade acionarão incrementos major com notas de migração.

Versões pré-lançamento?

Use 1.2.0-alpha.1 em Cargo.toml para pré-lançamentos no crates.io.

Repositório apenas de binário versionamento?

Tags Git e tags de container importam mais que crates.io; ainda assim embuta CARGO_PKG_VERSION.

Como depreciar APIs?

#[deprecated(since = "0.4.0", note = "use new_fn")] mais entrada no changelog.

Relacionados

Versões da Stack: Esta página foi escrita para Rust 1.97.0 (edição 2024), Tokio 1.x, Axum 0.8, serde 1.0, sqlx 0.8, clap 4, e Polars 0.46+.

Release & Versioning

Rust usa SemVer em Cargo.toml. Aplicações marcam releases no git; bibliotecas publicam no crates.io com entradas de changelog e promessas de estabilidade de API.

Receita

# Instalar helper de release
cargo install cargo-release
 
# Incrementar versão patch, atualizar lock, marcar
cargo release patch --execute

# Cargo.toml
[package]
name = "my-lib"
version = "0.3.2"
rust-version = "1.97"

Quando usar isto:

Publicando crates de workspace
Distribuindo ferramentas CLI com saída --version
Coordenando mudanças de API que quebram compatibilidade entre dependentes

Exemplo em Funcionamento

# Serviço binário: tag git direciona o deploy
git tag v2.1.0
git push origin v2.1.0
# CI constrói o container ghcr.io/acme/api:2.1.0

// Expor a versão na CLI
const VERSION: &str = env!("CARGO_PKG_VERSION");
 
fn main() {
    println!("my-cli {VERSION}");
}

O que isto demonstra:

CARGO_PKG_VERSION embutido no tempo de compilação da versão
Tags Git alinhadas com tags de container
cargo-release automatiza o manifest + tag git

Mergulho Profundo

Regras SemVer para APIs Rust

Mudança	Incremento
Quebra de trait/struct público	Major (1.0+) ou minor (0.x)
Nova API aditiva	Minor
Correção de bug, interna	Patch

#[non_exhaustive] e traits selados suavizam a evolução para bibliotecas.

Mudança que quebra em patch - quebra downstream. Correção: CI com cargo semver-checks.
Esqueceu de publicar todos os membros do workspace - descompasso de versão. Correção: checklist de release por crate.
Crate 0.x tratado como estável - SemVer permite quebras em minor. Correção: documentar a política de estabilidade.
Tag Git sem atualização do lockfile - builds de tag não reproduzíveis. Correção: commitar lock com a tag.
Crate yanked deixado no lock - cargo build falha. Correção: cargo update -p crate prontamente.

Alternativas

Alternativa	Usar Quando	Não Usar Quando
`release-plz`	Workspaces com múltiplos crates	Repositório de binário único
Incremento manual de versão	Controle total	Releases frequentes
Versionamento por calendário	Apenas deploy SaaS	Bibliotecas publicadas

FAQs

Quando atingir 1.0?

Quando o contrato da API pública for estável e mudanças que quebram compatibilidade acionarão incrementos major com notas de migração.

Versões pré-lançamento?

Use 1.2.0-alpha.1 em Cargo.toml para pré-lançamentos no crates.io.

Repositório apenas de binário versionamento?

Tags Git e tags de container importam mais que crates.io; ainda assim embuta CARGO_PKG_VERSION.

Como depreciar APIs?

#[deprecated(since = "0.4.0", note = "use new_fn")] mais entrada no changelog.

Relacionados

Versões da Stack: Esta página foi escrita para Rust 1.97.0 (edição 2024), Tokio 1.x, Axum 0.8, serde 1.0, sqlx 0.8, clap 4, e Polars 0.46+.

Release & Versioning

Buscar na documentação

Release & Versioning