Sistema de Versionamento Automático - SGE 3.0

Este documento explica como funciona o sistema de versionamento automático do SGE 3.0.

📋 Índice

• Como Funciona
• Guia Rápido
• Fluxos de Deploy
• Estrutura de Arquivos
• Comandos Disponíveis
• Troubleshooting
• FAQ

---

Como Funciona

A versão exibida no sistema é gerada automaticamente incluindo: - 📅 Data e hora do build (formato: dd/MM/yy HH:mm) - 🔀 Branch do Git (ex: develop, feature/xyz) - 🔖 Commit hash (versão curta, 8 caracteres)

Exemplo de versão gerada:

SGE 3.0 (05/11/25 20:35) [develop@7b2d72a5]

Conceito Principal

O arquivo src/Nelmetais.SGE.Business/BuildInfo.cs: - ✅ Gerado automaticamente durante o build (MSBuild Target) - ✅ NÃO é versionado no Git (está no .gitignore) - ✅ make build e dotnet build geram automaticamente - ✅ Para Docker: make deploy-homolog-build gera antes do build - ✅ Git nunca reclama - arquivo sempre ignorado

---

Guia Rápido

Para Desenvolvimento Local

# Qualquer comando de build gera versão automaticamente
make build
dotnet build
make run-dev
make run-watch

# Atualizar versão sem build (opcional - para Docker)
make generate-version

IMPORTANTE: - ✅ TODOS os builds geram versão automaticamente (MSBuild Target) - ✅ make build, dotnet build, make run-dev, etc. - TODOS geram versão - ✅ Git NUNCA reclama - BuildInfo.cs está no .gitignore - ✅ Não precisa commitar BuildInfo.cs - é sempre gerado

Para Homologação

# Um único comando faz tudo
make deploy-homolog-build

O que acontece: 1. ✅ make generate-version é executado automaticamente 2. ✅ BuildInfo.cs é atualizado com data, hora, branch e commit atuais 3. ✅ Docker build usa o arquivo atualizado 4. ✅ Deploy completo com versão correta

Para Produção

# 1. No repositório de produção (antes do sync/commit):
make generate-version

# 2. Verificar o arquivo gerado:
cat src/Nelmetais.SGE.Business/BuildInfo.cs

# 3. Commitar o arquivo atualizado:
git add src/Nelmetais.SGE.Business/BuildInfo.cs
git commit -m "Update version info for deploy"

# 4. Push para o repositório de produção
git push

# 5. O pipeline/deploy normal vai usar o BuildInfo.cs commitado

---

Fluxos de Deploy

Fluxo 1: Homologação (Automático)

┌──────────────────────────────────────────────┐
│ make deploy-homolog-build                    │
├──────────────────────────────────────────────┤
│ 1. docker system prune                       │
│ 2. make generate-version (automático)        │
│    → Atualiza BuildInfo.cs                   │
│    → Data/hora atual + Git info              │
│ 3. docker-compose build                      │
│    → Copia src/ (com BuildInfo.cs atualizado)│
│ 4. Deploy completo                           │
└──────────────────────────────────────────────┘

Resultado: SGE 3.0 (05/11/25 20:35) [develop@7b2d72a5]

Fluxo 2: Produção (Manual + CI/CD)

┌──────────────────────────────────────────────┐
│ 1. Local (antes de commitar):                │
│    make generate-version                     │
│    git add BuildInfo.cs                      │
│    git commit -m "Update version"            │
│    git push                                  │
├──────────────────────────────────────────────┤
│ 2. Sync entre repos (Bitbucket → Git):       │
│    BuildInfo.cs já está commitado            │
├──────────────────────────────────────────────┤
│ 3. Pipeline/Deploy:                          │
│    Docker build usa BuildInfo.cs commitado   │
│    Deploy normal funciona                    │
└──────────────────────────────────────────────┘

Resultado: SGE 3.0 (05/11/25 20:35) [main@abc123de]

Fluxo 3: Desenvolvimento Local

┌──────────────────────────────────────────────┐
│ make build                                   │
├──────────────────────────────────────────────┤
│ 1. restore (dependências NuGet)              │
│ 2. make generate-version (automático)        │
│    → Atualiza BuildInfo.cs com Git info      │
│    → Data/hora atual                         │
│ 3. dotnet build                              │
└──────────────────────────────────────────────┘

Resultado: Versão SEMPRE atualizada

┌──────────────────────────────────────────────┐
│ dotnet build (direto, sem Makefile)          │
├──────────────────────────────────────────────┤
│ → NÃO gera versão nova                       │
│ → Usa BuildInfo.cs existente                 │
│ → Build funciona (fallback seguro)           │
└──────────────────────────────────────────────┘

Resultado: Última versão gerada ou valores padrão

---

Estrutura de Arquivos

BuildInfo.cs (Versionado no Git)

Localização: src/Nelmetais.SGE.Business/BuildInfo.cs

Status: ✅ NÃO versionado no Git (está no .gitignore)

Gerado automaticamente durante build:

public static class BuildInfo
{
    public const string BuildDate = "05/11/25 20:35";
    public const string GitCommitHash = "7b2d72a5";
    public const string GitBranch = "develop";
    public const string FullVersion = "SGE 3.0 (05/11/25 20:35) [develop@7b2d72a5]";
}

ConstantConfiguration.cs

Localização: src/Nelmetais.SGE.Business/ConstantConfiguration.cs

public class ConstantVersao
{
    // Versão agora é gerada automaticamente via BuildInfo.cs
    public static string Versao => BuildInfo.FullVersion;
    public static string AmbienteDesenvolvimento => "Ambiente de Desenvolvimento - " + Versao;
    public static string AmbienteProducao => "Ambiente de Produção - " + Versao;
}

View da Home

Localização: src/Nelmetais.SGE.WebApp/Views/Home/Index.cshtml

Exibe a versão automaticamente:

<environment include="Development">
    <h4>@ConstantVersao.AmbienteDesenvolvimento</h4>
</environment>
<environment include="Production">
    <h4>@ConstantVersao.AmbienteProducao</h4>
</environment>

---

Comandos Disponíveis

Gerar Versão

# Gera/atualiza BuildInfo.cs com informações do Git atual
make generate-version

O que faz: 1. Extrai commit hash curto: git rev-parse --short HEAD 2. Extrai nome da branch: git rev-parse --abbrev-ref HEAD 3. Captura data/hora atual: date '+%d/%m/%y %H:%M' 4. Sobrescreve src/Nelmetais.SGE.Business/BuildInfo.cs

Deploy Homologação

# Build completo para homologação (gera versão automaticamente)
make deploy-homolog-build

Sequência: 1. docker system prune -f (limpa espaço) 2. make generate-version (atualiza versão) 3. docker-compose build (build da imagem)

Build Normal

# Build local (GERA VERSÃO AUTOMATICAMENTE)
make build

# Build com rebuild completo (GERA VERSÃO AUTOMATICAMENTE)
make rebuild

# Build direto sem atualizar versão (usa BuildInfo.cs existente)
dotnet build

Diferença: - make build → Gera versão nova + compila - dotnet build → Apenas compila (versão não muda)

Ver Versão Atual

# Ver conteúdo do BuildInfo.cs
cat src/Nelmetais.SGE.Business/BuildInfo.cs

# Ver apenas a versão
grep FullVersion src/Nelmetais.SGE.Business/BuildInfo.cs

Outros Comandos

# Ver todos os comandos disponíveis
make help

# Build e executar
make build
make run-fast

---

Troubleshooting

❌ Erro: "BuildInfo não existe no contexto atual"

Causa: O arquivo BuildInfo.cs foi deletado ou não existe.

Solução:

# Restaurar do Git
git checkout src/Nelmetais.SGE.Business/BuildInfo.cs

# Ou gerar novamente
make generate-version

⚠️ Versão mostrando apenas datetime (sem branch/commit)

Causa: Git não está disponível no ambiente (comum em pipelines CI/CD).

Comportamento esperado: - Versão exibida: SGE 3.0 (05/11/25 20:59) (apenas data/hora) - GitCommitHash: n/a - GitBranch: n/a

Quando acontece: - Build em ambiente sem Git instalado - Pipeline CI/CD que não tem acesso ao repositório Git - Diretório não é um repositório Git

Isso é normal: O sistema foi projetado para degradar graciosamente quando Git não está disponível

⚠️ Versão antiga sendo exibida

Causa: Cache de build ou BuildInfo.cs não foi atualizado.

Solução:

# Opção 1: Rebuild completo
make clean
make generate-version
make build

# Opção 2: Forçar atualização e rebuild
make rebuild

❌ make generate-version falha

Causa: Git não está disponível ou não é um repositório Git.

Solução:

# Verificar se Git está funcionando
git status

# Se não for um repo Git, inicializar
git init
git add .
git commit -m "Initial commit"

# Então gerar versão
make generate-version

⚠️ Docker build não usa versão atualizada

Causa: BuildInfo.cs não foi gerado antes do build.

Solução:

# Usar o comando correto que gera versão automaticamente
make deploy-homolog-build

# Ou manualmente:
make generate-version
docker-compose -f docker-compose.onpremise.yml build nelmetais.sge.webapp

---

FAQ

🤔 O build vai quebrar se eu não rodar make generate-version?

NÃO. O arquivo BuildInfo.cs está versionado no Git com valores padrão. O build sempre funciona.

🤔 Preciso rodar make generate-version toda vez?

Depende do contexto:

• Desenvolvimento local:
• ✅ make build → Gera automaticamente, não precisa rodar manualmente
• ✅ make run-dev → Gera automaticamente
• ⚠️ dotnet build → NÃO gera, usa versão existente
• Homologação: Não precisa rodar manualmente - make deploy-homolog-build faz automaticamente
• Produção: Sim, execute manualmente antes de commitar

🤔 O Dockerfile foi modificado?

NÃO. O Dockerfile está exatamente como estava antes. A solução foi simplificada para: 1. Gerar BuildInfo.cs antes do Docker build 2. Docker copia src/ com BuildInfo.cs já atualizado

🤔 BuildInfo.cs deve ser commitado no Git?

SIM. Agora ele está versionado e deve ser commitado: - Para desenvolvimento: commit com valores padrão ou última versão gerada - Para produção: commit após executar make generate-version

🤔 O que acontece se Git não estiver disponível?

O sistema funciona normalmente mas gera uma versão simplificada: - Com Git: SGE 3.0 (05/11/25 20:59) [develop@7b2d72a5] - Sem Git: SGE 3.0 (05/11/25 20:59)

Os campos GitCommitHash e GitBranch ficam como "n/a" quando Git não está disponível.

🤔 Como funciona para produção se não tenho acesso ao servidor?

1. No repositório local (antes do sync): make generate-version
2. Commit o BuildInfo.cs atualizado
3. Push para o repositório de produção
4. O deploy normal usa o arquivo commitado

🤔 Posso editar BuildInfo.cs manualmente?

Não recomendado. O arquivo é sobrescrito por make generate-version. Se precisar de valores específicos, ajuste o comando no Makefile.

🤔 Onde a versão aparece no sistema?

Tela inicial (Home): - Desenvolvimento: "Ambiente de Desenvolvimento - SGE 3.0 (05/11/25 20:35) [develop@7b2d72a5]" - Produção: "Ambiente de Produção - SGE 3.0 (05/11/25 20:35) [main@7b2d72a5]"

---

Garantias de Funcionamento

Cenário	BuildInfo.cs	Build	Versão Exibida
make build	Atualizado automaticamente	✅ Funciona	Versão atual do Git (ou datetime se Git indisponível)
dotnet build	Gerado automaticamente pelo MSBuild	✅ Funciona	Versão atual do Git (ou datetime se Git indisponível)
make deploy-homolog-build	Atualizado automaticamente	✅ Funciona	Versão atual do Git (ou datetime se Git indisponível)
Produção (após generate-version + commit)	Commitado no Git	✅ Funciona	Versão commitada
Git não disponível	Gerado com datetime apenas	✅ Funciona	SGE 3.0 (dd/mm/yy HH:MM) (sem branch/commit)
BuildInfo.cs deletado	Regenerado automaticamente	✅ Funciona	Versão atual (MSBuild regenera)

---

Degradação Graciosa (Fallback)

O sistema foi projetado para funcionar mesmo em ambientes sem Git:

Com Git Disponível

SGE 3.0 (05/11/25 20:59) [develop@7b2d72a5]

- BuildDate: 05/11/25 20:59 - GitCommitHash: 7b2d72a5 - GitBranch: develop - FullVersion: SGE 3.0 (05/11/25 20:59) [develop@7b2d72a5]

Sem Git Disponível (Fallback)

SGE 3.0 (05/11/25 20:59)

- BuildDate: 05/11/25 20:59 - GitCommitHash: n/a - GitBranch: n/a - FullVersion: SGE 3.0 (05/11/25 20:59) (sem informações Git)

Como Funciona o Fallback

MSBuild Target (Nelmetais.SGE.Business.csproj):

<!-- Se Git retorna "unknown", remove informações Git da versão -->
<PropertyGroup Condition="'$(GitCommitHashClean)' == 'unknown' OR '$(GitBranchClean)' == 'unknown'">
    <GitInfoSuffix></GitInfoSuffix>
    <GitCommitHashClean>n/a</GitCommitHashClean>
    <GitBranchClean>n/a</GitBranchClean>
</PropertyGroup>

Makefile (generate-version):

if [ "$GIT_COMMIT" = "unknown" ] || [ "$GIT_BRANCH" = "unknown" ]; then
    GIT_INFO_SUFFIX=""
    GIT_COMMIT="n/a"
    GIT_BRANCH="n/a"
    FULL_VERSION="SGE 3.0 ($BUILD_DATE)"
fi

Cenários Comuns de Fallback

1. Pipeline CI/CD sem Git: Build funciona normalmente, mostra apenas datetime
2. Docker build sem Git: Se Git não estiver no container, versão simplificada é gerada
3. Build em diretório não-Git: Sistema funciona sem erros

Vantagem: O build NUNCA quebra por falta de Git - apenas gera versão simplificada.

---

Benefícios

✅ Rastreabilidade: Saber exatamente qual commit está rodando ✅ Simplicidade: Não requer mudanças no Dockerfile ✅ Flexível: Funciona para desenvolvimento, homologação e produção ✅ Seguro: Fallback com valores padrão - build nunca quebra ✅ Debug Fácil: Identificar rapidamente qual versão tem problemas ✅ Suporte: Usuários podem reportar a versão exata ✅ CI/CD Ready: Funciona em qualquer pipeline ✅ Controle Total: Para produção, você decide quando atualizar

---

Arquivos Modificados

• ✅ Makefile - deploy-homolog-build executa generate-version automaticamente
• ✅ Makefile - Novo comando generate-version
• ✅ src/Nelmetais.SGE.Business/BuildInfo.cs - Agora versionado no Git
• ✅ src/Nelmetais.SGE.Business/ConstantConfiguration.cs - Usa BuildInfo.FullVersion
• ✅ .gitignore - Removido BuildInfo.cs

Não modificados: - ✅ deploy/Dockerfile - Permanece original - ✅ docker-compose.onpremise.yml - Sem mudanças

---

Resumo

Antes: - Versão hardcoded em ConstantConfiguration.cs - Impossível rastrear qual código está em produção

Agora: - ✅ Versão automática com data, hora, branch e commit - ✅ make deploy-homolog-build gera tudo automaticamente - ✅ Para produção: make generate-version + commit - ✅ Build nunca quebra - fallback seguro - ✅ Dockerfile não foi alterado - ✅ Simples e confiável

Tudo funciona. Nada quebra. Rastreabilidade completa. 🎉