Versionamento & Build

Versionamento independente

Projetos Lino podem conter vários serviços e aplicações web. Cada item implantável possui sua própria versão, então uma correção pequena em um serviço não força um release artificial de todo o sistema. Isso é importante em arquiteturas modulares e distribuídas, nas quais APIs, workers, web apps, migrations e contratos de integração podem evoluir em ritmos diferentes.

A versão operacional é armazenada em um arquivo de texto simples chamado version.txt. Para serviços, o arquivo fica em src/Services/<ServiceName>/version.txt. Para aplicações web, ele fica em src/WebApps/<WebAppName>/version.txt. O CLI do Lino lê esses arquivos ao listar, consultar, incrementar e gerar builds versionados.

Regra SemVer usada pelo Lino

MAJOR.MINOR.PATCH

• PATCH incrementa o último número e deve ser usado para correções compatíveis, pequenas melhorias internas e mudanças que não alteram o contrato público.
• MINOR incrementa o número do meio e zera o patch. Use para funcionalidades retrocompatíveis, novos endpoints, campos opcionais ou comportamento aditivo.
• MAJOR incrementa o primeiro número e zera minor e patch. Use quando consumidores precisam se adaptar, por exemplo porque um contrato de API mudou de forma incompatível ou um comportamento foi substituído intencionalmente.

Exemplos: 1.0.0 pode representar a primeira versão estável, 1.0.1 uma correção compatível, 1.1.0 uma nova capacidade compatível ou novos endpoints sem quebra, e 2.0.0 um release com mudanças que exigem atualização dos clientes.

Consultar versões atuais

Use lino version list para ver as versões atuais de todos os serviços e aplicações web do projeto:

lino version list

Use lino version show quando precisar consultar a versão de um serviço ou aplicação web específica. O comando pergunta se o alvo é um serviço ou uma aplicação web e exibe a versão lida do arquivo version.txt correspondente.

lino version show

Incrementar uma versão

Use lino version bump quando um serviço ou aplicação web estiver pronto para um novo release:

lino version bump

1. Execute o comando a partir da raiz do projeto.
2. Selecione um ou mais serviços ou aplicações web. O prompt mostra cada item com sua versão atual.
3. Escolha o tipo de incremento: patch, minor ou major.
4. Confirme as respostas. O Lino atualiza os arquivos version.txt selecionados e exibe uma tabela com as novas versões.

Cada execução mantém um rastreamento claro de mudanças, melhora a consistência com práticas de release e facilita o alinhamento com pipelines de CI/CD. O número de versão deixa de ser um detalhe solto e passa a identificar o artefato implantável que realmente mudou.

Mudanças de versão devem ser revisadas junto com o impacto técnico do release. Uma migration de banco pode estar vinculada à versão de um serviço, consumidores de API podem precisar de notas de contrato e eventos de integração podem exigir checagens de compatibilidade. Manter a versão próxima do item implantável torna essas decisões explícitas e mais fáceis de auditar.

Antes de um incremento major, revise APIs públicas, contratos de eventos, migrations, compatibilidade de clientes e consumidores externos. Antes de um incremento minor, confirme que o comportamento novo é aditivo. Antes de um patch, confirme que a alteração é compatível e não muda expectativas de uso.

Build e conteinerização

Nos vídeos e no desenvolvimento diário, dotnet build é usado com frequência para validar se a solução gerada ainda compila depois de cada etapa de modelagem. O comando lino build tem outro objetivo: preparar serviços e aplicações web selecionados para release, publicando-os em modo Release com o perfil de publicação de container do .NET.

Essa separação evita tratar uma simples validação de compilação como pacote de entrega. Use dotnet build durante desenvolvimento para encontrar erros cedo. Use lino build quando o artefato estiver pronto para receber versão, virar imagem de container e seguir para um registry ou pipeline de implantação.

O que o lino build faz

Execute o comando a partir da raiz de um projeto Lino:

lino build

O CLI valida o usuário autenticado e a configuração atual do projeto, pergunta quais serviços ou aplicações web devem entrar no build e, em seguida, pergunta se a versão deve ser mantida ou incrementada. Quando um incremento é selecionado, o Lino atualiza o version.txt correspondente antes de gerar os comandos de build.

O backend retorna os comandos exatos a executar. Atualmente, esses comandos usam dotnet publish com -c Release, -p:PublishProfile=DefaultContainer, -p:ContainerRepository, -p:ContainerImageTag e -p:ContainerLabelVersion. A tag da imagem e o label de versão do container recebem o mesmo valor SemVer escolhido para o release.

Na prática, o processo compila o código do serviço ou da aplicação web, aplica a configuração de publicação necessária, gera uma imagem de container baseada na versão SemVer atual e atribui nome, tag e metadados padronizados ao artefato.

Nomes de repositório gerados

O Lino normaliza os nomes do projeto e dos itens para gerar repositórios de container previsíveis:

• API de serviço simples: <project-name>/services/<service-name>-api:1.2.3
• Host de serviço modular: <project-name>/services/<service-name>-host:1.2.3
• Aplicação web Blazor: <project-name>/webapps/<webapp-name>:1.2.3

Essa convenção mantém APIs de serviços, hosts modulares e aplicações web separados no registry, preservando a versão de release na tag. O padrão também elimina decisões manuais repetitivas e reduz divergências entre ambientes, scripts de CI/CD e documentação operacional.

Publicação em registries

As imagens geradas podem ser publicadas no registry usado pela sua plataforma de deploy:

• Docker Hub
• GitHub Container Registry
• AWS ECR
• Azure Container Registry
• qualquer outro registry compatível com OCI.

Sempre que possível, faça deploy apontando para tags imutáveis de versão, como 1.2.3, em vez de tags flutuantes. Isso melhora rollback, auditoria e comparação entre o que foi compilado, publicado e implantado.

Fluxo recomendado de release

1. Execute os testes do projeto e dotnet build para validar o código-fonte antes de empacotar.
2. Consulte as versões atuais com lino version list e revise quais serviços ou aplicações web mudaram.
3. Use lino build e escolha se a versão atual será mantida ou se receberá incremento patch, minor ou major.
4. Publique as imagens de container geradas no registry usado pela plataforma de implantação, como Docker Hub, GitHub Container Registry, AWS ECR, Azure Container Registry ou outro registry compatível.
5. Implante referenciando tags de versão rastreáveis e mantenha changelog, migrations e plano de rollback conectados ao mesmo release.

Não coloque secrets, connection strings de produção nem credenciais específicas de ambiente dentro das imagens geradas. Use variáveis de ambiente, user secrets para desenvolvimento local, cofres de secrets do CI/CD ou o mecanismo de secrets da plataforma de deploy.

Com esse fluxo, versionamento e build ficam ligados: o mesmo valor SemVer gravado no projeto é usado como tag de container e como metadado de release, melhorando a rastreabilidade entre código-fonte, migrations, contratos de API, eventos de integração e artefatos implantados.