Boas práticas de versionamento Git para Power BI (.pbip)

Introdução

Público: Analistas de dados que já sabem Git básico mas versionam .pbix como binário.

Objetivo: migrar para fluxo PBIP + commits atômicos, com exemplos práticos (curva ABC para clientes), checklist e automações com Tabular Editor/Git LFS/Power BI Service.

Analogia rápida: um commit é como um ponto de verificação (save point) em um jogo — deve salvar um estado consistente, reproduzível e reversível, não o replay inteiro.

---

1. Por que usar PBIP?

• .pbip salva o relatório e o modelo como pastas e arquivos de texto (JSON/TOM/TMSL etc.), tornando possível diff/merge e revisão por linha.
• Com PBIP + serialização do modelo (via Tabular Editor / “Save to Folder”) você transforma medidas, calculation items e metadados em arquivos legíveis, permitindo diffs e automação.
• Para arquivos binários grandes (quando existir .pbix ou assets grandes), use Git LFS e bloqueio de arquivos para evitar sobrescritas simultâneas.
• PBIP pode ser integrado em pipelines/CD (Fabric/Power BI APIs) para deploy automatizado do projeto.

---

2. Nomenclatura de commits — Conventional Commits adaptado para Power BI

Formato exigido:

<tipo>(<escopo>): <descrição curta>

Tipos e exemplos adaptados:

• feat(dax): nova medida calculada
• fix(viz): correção de interação visual
• style(layout): ajuste de tema e fontes
• refactor(model): reorganização de tabelas/relacionamentos
• docs(measure): comentários em DAX / documentação de medidas
• chore(pbip): atualização de versão do projeto / dependências

Escopos sugeridos: dax, viz, model, layout, data, config

Exemplos reais — Curva ABC (5 commits)

1. feat(dax): cria função CategorizaABC(cliente, venda) para classificação ABC
2. feat(dax): adiciona medida %Acumulado para Pareto (curva)
3. refactor(model): adiciona coluna Cliente.Categoria_ABC e index para ordenação
4. fix(viz): corrige filtro do gráfico Pareto que ignorava seleção de datas
5. docs(measure): documenta lógica CategorizaABC e casos de borda (0 vendas)

---

3. Quando fazer commits — Regra do “Undo Test”

Definição (Undo Test): Antes de commitar, pergunte-se: posso reverter este commit e o projeto ficará em um estado consistente e testável? Se sim, commite. Se não, divida.

Regras específicas

Sempre commitar quando

• Lógica DAX complexa funcionar e estiver coberta por um teste manual (ex.: validar soma por cliente).
• Um visual ficar funcional (o gráfico apresenta filtros e interação esperada).
• Correção de bug concluída.
• Documentação (comentários DAX/README) concluída.

Nunca commitar quando

• Experimentos descartáveis (prototipagem rápida): mantenha em stash ou branch wip/*.
• Ajustes visuais em progresso (rodar várias iterações antes de commitar).
• Arquivos temporários (.tmp, exports experimentais) staged acidentalmente.

Fluxo passo-a-passo — criando a página Curva ABC (onde pausar para commits)

1. git checkout -b feature/curva-abc-clientes

Fase DAX: categorização

• Implementar CategorizaABC em Tabular Editor (ou salvar em arquivo DAX).
• Teste: valida 10 clientes com vendas conhecidas.
• Pause & Commit:

git add models/measures/CategorizaABC.dax
git commit -m "feat(dax): cria função CategorizaABC(cliente, venda) para classificação ABC"

Fase Model: criar coluna calculada Cliente.Categoria_ABC e índices

• Teste: agrupe por categoria e confira contagens.
• Pause & Commit:

git add semanticmodel/Cliente.Categoria_ABC.*
git commit -m "refactor(model): adiciona coluna Cliente.Categoria_ABC e índice de ordenação"

Fase Visual: construir gráfico Pareto e tabela ABC

• Teste: interações de filtro, drillthrough, tooltip.
• Pause & Commit:

git add report/pages/curva-abc.*
git commit -m "feat(viz): adiciona página Curva ABC com gráfico Pareto e tabela detalhada"

Validação & Bugfix: se encontrar bug de filtro (exemplo)

# corrigir
git add models/measures/FiltroPareto.dax
git commit -m "fix(viz): corrige filtro do gráfico Pareto que ignorava intervalo de datas"

---

4. Quando criar branches — Git Flow simplificado para Power BI

Regras principais:

• main → Código publicado no Power BI Service (produção).
• feature/ → cada nova tela/métrica (ex.: feature/curva-abc-clientes).
• fix/ → correções urgentes locais (ex.: fix/categoria-abc-filtro-data).
• hotfix/ → bugs em produção (feito a partir de main, deploy rápido).
• refactor/ → refatoração de modelo que altera estrutura (tabelas, chaves).

Regra de ouro: crie nova branch para qualquer alteração que demore > 25 minutos ou possa ser revertida independentemente.

---

5. Exemplos Práticos (comandos, mensagens)

Cenário A — Commit atômico correto

git checkout -b feature/curva-abc-clientes
# editar arquivo: models/measures/CategorizaABC.dax
git add models/measures/CategorizaABC.dax
git commit -m "feat(dax): cria função CategorizaABC(cliente, venda) para classificação ABC"
git push -u origin feature/curva-abc-clientes

Explicação: commit contém apenas a medida (único objetivo), é reversível e testável.

Cenário B — Commit muito grande (anti-padrão) e como dividir

Anti-padrão (ERRADO):

# NÃO FAÇA
git add .
git commit -m "implementa curva ABC e melhorias várias"

Como dividir (correto):

# desfazer se já cometeu
git reset HEAD~1

# depois usar git add -p para selecionar hunks
git add -p models/measures/CategorizaABC.dax
git commit -m "feat(dax): cria CategorizaABC"

git add -p semanticmodel/Cliente.Categoria_ABC.*
git commit -m "refactor(model): adiciona coluna Cliente.Categoria_ABC"

git add report/pages/curva-abc.*
git commit -m "feat(viz): adiciona página Curva ABC com gráfico Pareto"

git add docs/README.md
git commit -m "docs(measure): documenta cálculo e validação da Curva ABC"

Cenário C — Branch desnecessária vs. branch essencial

Branch desnecessária (anti-padrão): criar feature/wip-visuals para um ajuste de 5 minutos no layout do título.

Branch essencial: alteração na granularidade do modelo — criar nova tabela agregada Vendas_Mensais.

git checkout -b refactor/add-ventas-mensais
# implementar mudanças
git add semanticmodel/Tables/Vendas_Mensais.*
git commit -m "refactor(model): adiciona tabela Vendas_Mensais para agregação mensal"
git push -u origin refactor/add-ventas-mensais

---

6. Checklist de validação PRÉ-COMMIT

• DAX exportado para texto via Tabular Editor?
• .gitignore ignorando Cache/ e arquivos .local*?
• Arquivos .gitattributes configurados com LFS?
• Mensagem segue formato tipo(escopo): descrição?
• Alterações testadas no Desktop?
• Apenas arquivos relevantes staged (use git add -p)?

Exemplo .gitattributes

# Git LFS rules
*.pbix filter=lfs diff=lfs merge=lfs -text
*.pbit filter=lfs diff=lfs merge=lfs -text

Exemplo .gitignore (trecho)

# Power BI / PBIP temporary
Cache/
*.local*
*.tmp
.vscode/

---

7. Saída prática: arquivos auxiliares e automações

7.1 commit-msg hook (verificador simples em bash)

Crie .githooks/commit-msg e instale com git config core.hooksPath .githooks.

#!/bin/bash
MSG_FILE=$1
MSG=$(cat "$MSG_FILE")

# Regex: tipo(escopo): descrição
if [[ ! $MSG =~ ^(feat|fix|style|refactor|docs|chore)\([a-zA-Z0-9_-]+\):\s.+ ]]; then
  echo "Mensagem de commit inválida. Use tipo(escopo): descrição\nEx: feat(dax): nova medida" >&2
  exit 1
fi

Torne executável:

chmod +x .githooks/commit-msg
git config core.hooksPath .githooks

7.2 Script Tabular Editor (C#) para exportar medidas automaticamente

Coloque este script em Tabular Editor -> Advanced Scripting e ajuste folder.

var folder = @"./semanticmodel/measures/";
System.IO.Directory.CreateDirectory(folder);
foreach(var m in Model.AllMeasures) {
    var safeName = string.Join("_", m.Name.Split(Path.GetInvalidFileNameChars()));
    var path = System.IO.Path.Combine(folder, safeName + ".dax");
    System.IO.File.WriteAllText(path, "-- " + m.Name + "\n" + m.Expression);
}

Dica: crie ação customizada no Tabular Editor que chama esse script para padronizar export.

7.3 Exemplo de pipeline (esquema)

• on: pull_request → executar validação de estrutura, rodar script que checa presença de arquivos obrigatórios e commit-msg (lint).
• on: push to main → build + deploy via Power BI REST API (ou Fabric) para ambiente de produção.

---

8. Tabela comparativa — commits bons vs. ruins

Característica	Commit bom	Commit ruim
Escopo	Único objetivo	Multiples objetivos
Mensagem	feat(dax): ...	implementa várias mudanças
Reversão	Fácil	Difícil
Revisão	Rápida	Lenta
Testes	Localizados	Longos/inconsistentes

---

9. Fluxograma (Mermaid) — ciclo de vida da branch

%% Diagrama de fluxo simplificado para Power BI Git Flow

gitGraph
   commit id: "Init"
   branch feature/curva-abc-clientes
   checkout feature/curva-abc-clientes
   commit id: "feat(dax): cálculo base ABC"
   commit id: "feat(viz): gráfico Pareto clientes"
   checkout main
   commit id: "chore(pbip): atualização de versão"
   merge feature/curva-abc-clientes tag: "release-v1.0"
   branch fix/categoria-abc-filtro-data
   checkout fix/categoria-abc-filtro-data
   commit id: "fix(viz): correção filtro data Pareto"
   checkout main
   merge fix/categoria-abc-filtro-data tag: "hotfix-v1.0.1"

---

10. Recomendações finais

• Adote PBIP como padrão para permitir diffs textuais.
• Sempre serialize medidas / calculation items com Tabular Editor (Save to Folder) e versioná-los.
• Use commits atômicos, mensagens no formato tipo(escopo): descrição, e branches para alterações significativas (>25 min).
• Configure .gitattributes e Git LFS para arquivos binários.
• Integre deploy via APIs / Pipelines quando possível (Power BI / Fabric REST APIs).