# Fluxo de Branches

O Runner usa um modelo de branches especifico para separar desenvolvimento de deploy.

# Estrutura

┌─────────────────────────────────────────────────────────────────┐
│                         REPOSITORIO                              │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│   dev ──────────────────► main ──────────────────► dist         │
│    │                       │                        │            │
│    │ Desenvolvimento       │ Releases               │ Deploy     │
│    │ Codigo fonte          │ Tags vX.Y.Z            │ Artefatos  │
│    │ Testes locais         │ Codigo estavel         │ Builds     │
│    │                       │                        │            │
│    ▼                       ▼                        ▼            │
│  Trabalho               Producao               CI/CD Runner      │
│   diario               aprovado              faz deploy aqui     │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

# Branch dev

Proposito: Desenvolvimento ativo

Workflow:

git checkout dev
git pull origin dev

# Fazer alteracoes
git add .
git commit -m "feat(modulo): nova funcionalidade"
git push origin dev

# Branch main

Proposito: Codigo estavel e releases

Workflow:

git checkout main
git pull origin main
git merge dev --no-ff -m "release: v1.2.0"
git tag -a v1.2.0 -m "Release v1.2.0"
git push origin main --tags

# Branch dist

Proposito: Artefatos de deploy (builds compilados)

O que deve conter:

• dist/ - Build compilado (frontend)
• src/ - Codigo Python (backend)
• .deploy.yml - Configuracao de deploy
• package.json ou version.json - Para extrair versao

O que NAO deve conter:

• node_modules/
• Arquivos de teste
• Codigo fonte nao compilado (frontend)
• Ferramentas de desenvolvimento

Workflow:

# Fazer build
npm run build

# Mudar para dist
git checkout dist

# Copiar artefatos
rm -rf dist/
cp -r ../build/dist ./dist/

# Commit e push
git add .
git commit -m "deploy: v1.2.0"
git push origin dist

# Runner detecta e faz deploy!

# Por Que Branches Separadas?

# Seguranca

• Codigo fonte nao vai para producao
• Artefatos buildados sao imutaveis
• Audit trail claro

# Performance

• Branch dist e menor (sem node_modules)
• Downloads mais rapidos
• Menos I/O no servidor

# Clareza

• dev = desenvolvimento
• main = releases
• dist = deploy

# Fluxo Completo

1. DESENVOLVIMENTO (dev)
   └── Commits diarios
   └── Testes locais
   └── Code review

2. RELEASE (main)
   └── Merge de dev
   └── Tag vX.Y.Z
   └── Changelog

3. BUILD (local)
   └── npm run build
   └── Gera artefatos

4. DEPLOY (dist)
   └── Copia artefatos
   └── Commit na dist
   └── Push aciona Runner

5. RUNNER
   └── Detecta mudanca
   └── Executa pipeline
   └── Notifica resultado

# Semantic Versioning

Use versionamento semantico nas tags:

MAJOR.MINOR.PATCH

v1.0.0  →  v1.0.1  (patch: bug fix)
v1.0.0  →  v1.1.0  (minor: nova feature)
v1.0.0  →  v2.0.0  (major: breaking change)

Release candidates:

v1.1.0-rc1
v1.1.0-rc2
v1.1.0  (versao final)

# Conventional Commits

Use commits padronizados:

feat(modulo): nova funcionalidade
fix(auth): corrige bug de login
docs(readme): atualiza documentacao
chore(deps): atualiza dependencias
refactor(api): melhora estrutura

# .gitignore da dist

# NAO ignorar dist/ - e o conteudo principal!
node_modules/
venv/
__pycache__/
.env
.env.local
.secrets
*.log
tests/
__tests__/
coverage/
.idea/
.vscode/

# Exemplo Pratico

# 1. Desenvolvimento

git checkout dev
echo "console.log('nova feature')" >> src/app.js
git add .
git commit -m "feat(app): adiciona nova feature"
git push origin dev

# 2. Release

git checkout main
git merge dev --no-ff -m "release: v1.3.0"
git tag -a v1.3.0 -m "Release v1.3.0"
git push origin main --tags

# 3. Build

npm run build
# Gera arquivos em build/dist/

# 4. Deploy

git checkout dist
rm -rf dist/
cp -r ../build/dist ./dist/
cp package.json ./
cp .deploy.yml ./
git add .
git commit -m "deploy: v1.3.0"
git push origin dist
# Runner detecta e deploya!

# 5. Voltar para Dev

git checkout dev