Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Guia de Lançamento e Distribuição do SDK

Este guia explica como os SDKs do PAEBIRU são construídos, publicados e distribuídos em Python (PyPI), TypeScript/JavaScript (npm) e Swift (SPM).

Fluxo de Trabalho de Lançamento (Release)

O lançamento de produção é acionado ao enviar uma tag git que corresponda a v* (por exemplo, v0.1.0).

git tag v0.1.0
git push origin v0.1.0

Isso aciona automaticamente o .github/workflows/release.yml, que:

  1. Constrói binários nativos (paebiru-node, paebiru-cli) para 6 alvos
  2. Constrói pacotes SDK (wheels Python, WASM TypeScript, bibliotecas Swift)
  3. Cria o lançamento no GitHub com todos os artefatos
  4. Publica nos gerenciadores de pacotes:
    • crates.io (crates Rust)
    • PyPI (wheels Python)
    • npm (TypeScript/JavaScript)
    • SPM (Swift Package Manager)

Estágios

Estágio 1: Construir Binários

Trabalho (Job): build (6 em paralelo)

Compila paebiru-node e paebiru-cli para:

  • Linux x86_64, ARM64, RISC-V
  • macOS x86_64, ARM64 (Apple Silicon)
  • Windows x86_64

Saída: Binários executáveis preparados como:

paebiru-node-x86_64-unknown-linux-gnu
paebiru-node-aarch64-apple-darwin
...

Duração: ~15-20 minutos

Estágio 2: Construir SDKs

Trabalho (Job): build-sdks (5 em paralelo)

SDK Python

  • Plataformas: Linux (x86_64, ARM64), macOS (x86_64, ARM64), Windows (x86_64)
  • Ferramenta: maturin (sistema de construção PyO3)
  • Saída: Wheels (arquivos .whl)
  • Duração: ~5-10 minutos por plataforma

SDK TypeScript

  • Plataforma: Linux (constrói uma vez, alvo wasm32)
  • Ferramenta: wasm-pack
  • Saída: pacote npm (bundle)
  • Duração: ~3-5 minutos

SDK Swift

  • Plataformas: dispositivo iOS (arm64), simulador iOS (x86_64), macOS (Intel/Apple Silicon)
  • Ferramenta: cargo com alvos iOS
  • Saída: Bibliotecas nativas (arquivos .a, futuro .xcframework)
  • Duração: ~8-10 minutos por alvo

Estágio 3: Criar o Lançamento (Release)

Trabalho (Job): create-release

  • Verifica se a tag está na branch principal
  • Baixa todos os artefatos dos estágios 1 e 2
  • Cria o lançamento no GitHub com:
    • Notas de lançamento (geradas automaticamente a partir de commits)
    • Todos os artefatos binários
    • Wheels Python
    • Bundle do pacote TypeScript
    • Bibliotecas Swift

Duração: ~2 minutos

Estágio 4: Publicar nos Gerenciadores de Pacotes

Trabalhos (Jobs): publish-crates, publish-pypi, publish-npm, publish-spm

Crates Rust (crates.io)

  • Crates: paebiru-sdk, paebiru-zk, paebiru-learn, paebiru-hal, paebiru-node, paebiru-cli
  • Gatilho: Após a criação do lançamento
  • Duração: ~2-3 minutos

Wheels Python (PyPI)

  • Token: PYPI_TOKEN (requer configuração nos segredos do GitHub)
  • Ferramenta: twine
  • Versões: Todas as wheels da construção multiplataforma
  • Comando: twine upload wheels/**/*.whl --skip-existing
  • Duração: ~1-2 minutos

Pacote TypeScript (npm)

  • Token: NPM_TOKEN (requer configuração nos segredos do GitHub)
  • Escopo: @paebiru/sdk (opcional)
  • Ferramenta: npm publish
  • Duração: ~1 minuto

Pacote Swift (SPM)

  • Distribuição: Lançamentos do GitHub (automático)
  • Descoberta: Via Package.swift no git
  • Instalação: 
    .package(url: "https://github.com/silvanoneto/paebiru.git", from: "0.1.0")
  • Duração: Instantânea (já lançado no Estágio 3)

Requisitos de Configuração

Segredos do Repositório GitHub

Segredos necessários (adicione via GitHub Settings → Secrets and variables → Actions):

  1. CARGO_REGISTRY_TOKEN

    • Fonte: crates.io/me → “API Tokens”
    • Escopo: Acesso total para publicar crates
    • Tipo: Token de escrita

  2. PYPI_TOKEN

  3. NPM_TOKEN

  4. GITHUB_TOKEN (automático, fornecido pelo GitHub Actions)

    • Usado para criar lançamentos
    • Permissões: contents: write

Configuração Local para Testes

Para testar os lançamentos localmente antes de enviar (push):

# Wheels Python
cd crates/bindings/py
pip install maturin
maturin build --release

# TypeScript
cd crates/bindings/ts
npm install -g wasm-pack
wasm-pack build --release --target bundler

# Swift (dispositivo iOS)
cd crates/bindings/swift
cargo build --release --target aarch64-apple-ios

# Binários Rust
cargo auditable build --release -p paebiru-node -p paebiru-cli

Estratégia de Versionamento

Formato de Versão

Siga o Versionamento Semântico:

  • MAJOR.MINOR.PATCH (ex: 1.2.3)
  • Pré-lançamento: MAJOR.MINOR.PATCH-alpha.N, -beta.N, -rc.N
  • Metadados de construção: MAJOR.MINOR.PATCH+build.123 (raramente usado)

Regras

  • Incremente MAJOR para quebras de API
  • Incremente MINOR para novos recursos (compatíveis com versões anteriores)
  • Incremente PATCH para correções de bugs
  • Todos os SDKs são lançados na mesma versão (sincronizados)

Exemplos

v0.1.0          # Primeiro lançamento
v0.2.0          # Nova API de streaming
v1.0.0          # Integração ZK concluída
v1.0.1          # Correções de bugs
v1.1.0-rc1      # Candidato a lançamento para 1.1.0

Solução de Problemas

Construção da Wheel Python Falha

  • Problema: Erro de vinculação (linking) no macOS ARM64
  • Solução: Certifique-se de que o maturin está atualizado: pip install --upgrade maturin

Publicação no npm Rejeitada

  • Problema: Versão já existe
  • Solução: Verifique o registro npm ou incremente a versão de patch
  • Problema: Incompatibilidade de escopo
  • Solução: Atualize o escopo no package.json para @paebiru/sdk

Publicação no Crates.io Falha

  • Problema: Ordem de dependência
  • Solução: Certifique-se de que o paebiru-sdk seja publicado antes de crates/bindings/py/ts/swift na ordem
  • Problema: Dependência de crate removida (yanked)
  • Solução: Atualize o Cargo.lock e tente novamente

Integração do Swift SPM

  • Problema: Package.swift não encontrado
  • Solução: Certifique-se de que o Package.swift esteja no diretório crates/bindings/swift/
  • Problema: Falha no download do alvo binário
  • Solução: Verifique se os artefatos de lançamento do GitHub foram carregados e se a URL está correta

Processo de Lançamento Manual

Se o fluxo de trabalho automatizado falhar, lance manualmente:

# 1. Verifique se todos os testes passam
make test
# Ou manualmente excluindo bindings sensíveis:
# cargo test --workspace --exclude paebiru-r --exclude paebiru-php ...

# 2. Construa binários localmente
cargo auditable build --release -p paebiru-node -p paebiru-cli

# 3. Construa wheels Python (todas as plataformas)
cd crates/bindings/py && maturin build --release

# 4. Construa TypeScript
cd crates/bindings/ts && wasm-pack build --release --target bundler

# 5. Construa Swift
cd crates/bindings/swift && cargo build --release --target aarch64-apple-ios

# 6. Crie a tag git
git tag v0.X.Y
git push origin v0.X.Y

# 7. Publique no crates.io
cargo publish -p paebiru-sdk
cargo publish -p paebiru-zk
# ... etc

# 8. Publique wheels Python
cd crates/bindings/py/target/wheels
twine upload *.whl --repository pypi --token $PYPI_TOKEN

# 9. Publique TypeScript
cd crates/bindings/ts/pkg
npm publish --access public

# 10. Crie o lançamento no GitHub manualmente
# Visite https://github.com/silvanoneto/paebiru/releases/new
# Carregue arquivos de wheel, bundle WASM, bibliotecas Swift

Canais de Distribuição

PyPI (Python)

pip install paebiru

Plataformas suportadas:

  • Linux: x86_64, aarch64 (manylinux)
  • macOS: x86_64, arm64 (universal)
  • Windows: x86_64

Versões de Python: 3.8, 3.9, 3.10, 3.11, 3.12 (via compilação de wheel de recurso maturin)

npm (TypeScript)

npm install @paebiru/sdk
# ou
yarn add @paebiru/sdk

Alvos:

  • Bundlers (webpack, vite, rollup)
  • Navegador (tag script direta via CDN)
  • Node.js (CommonJS + ESM)

SPM (Swift)

// Package.swift
.package(url: "https://github.com/silvanoneto/paebiru.git", from: "0.1.0")

// Dependências
targets: [
    .target(name: "MyApp", dependencies: [.product(name: "Paebiru", package: "paebiru")])
]

Plataformas suportadas:

  • iOS 13+
  • macOS 10.15+

crates.io (Rust)

[dependencies]
paebiru-sdk = "0.1"
paebiru-node = "0.1"
paebiru-cli = "0.1"

Checklist Pós-Lançamento

  • Todos os gerenciadores de pacotes mostram a versão correta
  • O lançamento no GitHub tem todos os binários e arquivos wheel
  • A página do PyPI lista todas as variantes de wheel
  • O registro npm mostra o módulo correto com tipos TypeScript
  • O Package.swift do SPM resolve corretamente
  • Site de documentação atualizado para a nova versão
  • Notas de lançamento publicadas (post no blog opcional)
  • Anuncie nos canais da comunidade (Discord, Twitter, etc.)

Melhorias Futuras

  1. Geração automática de changelog a partir de commits convencionais
  2. Imagens Docker com binários pré-construídos
  3. Fórmula Homebrew para macOS/Linux
  4. Pacote Conan para integração C++
  5. Otimização da matriz do GitHub Actions para construções paralelas mais rápidas
  6. Lançamentos noturnos (canal alfa) para versões de desenvolvimento