AirData Docs

1. Visão Geral

Git é o sistema de controle de versão usado para registrar a evolução de arquivos ao longo do tempo. Ele permite saber o que mudou, quem mudou, quando mudou e por qual motivo. Em projetos de pesquisa, isso é essencial para preservar rastreabilidade, reproduzir análises e colaborar sem sobrescrever o trabalho de outra pessoa.

O GitHub é a plataforma onde os repositórios ficam publicados. O Git roda na sua máquina; o GitHub centraliza o repositório remoto, as branches compartilhadas, os pull requests, as revisões e o histórico acessível ao grupo.

Vocabulário mínimo

Repositório: pasta versionada pelo Git.
Commit: registro de uma mudança concluída.
Branch: linha de trabalho isolada.
Remote: cópia publicada, normalmente no GitHub.
Pull request: pedido de revisão e integração.

2. Configuração Inicial

Antes de contribuir, configure sua identidade local. Esses dados aparecem nos commits e ajudam a rastrear autoria de mudanças no projeto.

git config --global user.name "Seu Nome"
git config --global user.email "seu.email@instituicao.br"
git config --global init.defaultBranch main
git config --global pull.rebase true

Identidade

Use o mesmo e-mail associado ao GitHub institucional sempre que possível. Isso mantém autoria, revisão e histórico conectados.

Editor

Se o Git abrir um editor inesperado, configure seu editor preferido. Exemplo: git config --global core.editor "code --wait".

Acesso

Para repositórios privados, use autenticação do GitHub por HTTPS com token, GitHub CLI ou chave SSH cadastrada na conta.

3. Baixar e Atualizar Repositórios

Clonar é baixar uma cópia completa do repositório para a sua máquina. Faça isso uma vez por projeto. Depois disso, você apenas atualiza a cópia local com pull ou fetch. No ecossistema atual, os exemplos abaixo usam os repositórios GitHub da organização AirData-ITA: ita-airdata-quality-check, ita-airdata-pipelines, ita-airdata-ontology, ita-airdata-rag-system-llm e ita-airdata-owl.

Repositório de pipelines

git clone https://github.com/AirData-ITA/ita-airdata-pipelines.git
cd ita-airdata-pipelines
git status

Use HTTPS quando estiver configurado com login ou token do GitHub. É uma forma direta de baixar os repositórios da organização AirData-ITA.

Repositórios técnicos AirData

git clone git@github.com:AirData-ITA/ita-airdata-ontology.git
cd ita-airdata-ontology
git remote -v

Use SSH quando sua chave estiver cadastrada no GitHub. Para frentes como pipelines, ontologia, qualidade, RAG e OWL, mantenha a branch conectada ao domínio do repositório.

Qualidade de Dadosita-airdata-quality-checkAirData-ITA/ita-airdata-quality-check

Validações, consistência e acompanhamento de qualidade de dados.

git clone https://github.com/AirData-ITA/ita-airdata-quality-check.git

Engenharia de Dadosita-airdata-pipelinesAirData-ITA/ita-airdata-pipelines

Ingestão, transformação, orquestração e processamento.

git clone https://github.com/AirData-ITA/ita-airdata-pipelines.git

Modelagem Semânticaita-airdata-ontologyAirData-ITA/ita-airdata-ontology

Evolução da ontologia, conceitos, classes e relações do domínio.

git clone https://github.com/AirData-ITA/ita-airdata-ontology.git

IA / Consulta Semânticaita-airdata-rag-system-llmAirData-ITA/ita-airdata-rag-system-llm

Sistema RAG, recuperação contextual e integração com LLM.

git clone https://github.com/AirData-ITA/ita-airdata-rag-system-llm.git

Ontologia / Publicaçãoita-airdata-owlAirData-ITA/ita-airdata-owl

Portal de publicação e navegação dos artefatos ontológicos.

git clone https://github.com/AirData-ITA/ita-airdata-owl.git

Ação	Comando	Quando usar
Ver origem remota	`git remote -v`	Confirmar se o repositório aponta para o GitHub correto.
Buscar novidades	`git fetch --all --prune`	Atualizar referências sem mexer nos arquivos locais.
Atualizar branch	`git pull --rebase origin main`	Trazer a versão mais recente da branch principal.

4. Branches e Padrões de Criação

Branches separam linhas de trabalho. A regra prática é simples: nunca trabalhe diretamente na main quando a mudança ainda precisa de teste, revisão ou discussão. Crie uma branch com nome curto, descritivo e ligado ao objetivo.

Para os repositórios AirData, vale começar o nome pelo tipo da mudança e depois indicar o domínio afetado: pipelines, ontology, quality-check, rag ou docs. Isso deixa claro se a alteração está no fluxo de dados, na modelagem semântica, na qualidade, na camada de IA ou no portal documental.

feature/<tema-curto>

Nova funcionalidade, experimento ou melhoria planejada.

git switch -c feature/pipelines-ingestao-metar

fix/<problema>

Correção de bug sem alterar o escopo funcional principal.

git switch -c fix/quality-check-validacao-nulos

docs/<tema>

Mudanças em documentação, guias, README ou exemplos.

git switch -c docs/airdata-guia-git

chore/<tarefa>

Tarefas de manutenção, dependências, limpeza ou configuração.

git switch -c chore/ontology-atualiza-dependencias

experiment/<hipotese>

Prototipos e validações exploratórias que ainda não estão prontas para produção.

git switch -c experiment/rag-ranking-hibrido-airdata

Padrão recomendado para o AirData: uma branch por mudança rastreável, usando o domínio do ativo no nome e mantendo escopo pequeno o bastante para revisão objetiva.

5. Fluxo de Git no Dia a Dia

O fluxo abaixo cobre a rotina mais comum: atualizar a base, criar uma branch, fazer a mudança, registrar commits, publicar e abrir revisão.

Atualizar base

Comece a partir da versão mais recente da branch principal.

git switch main
git pull --rebase origin main

Sua main local fica alinhada ao GitHub antes de criar trabalho novo.

Criar branch

Isole a mudança em uma linha de trabalho clara.

git switch -c feature/pipelines-ingestao-metar

A tarefa fica separada da main e pronta para commits próprios.

Registrar mudança

Agrupe arquivos relacionados em um commit pequeno e descritivo.

git add .
git commit -m "feat: adiciona ingestao metar aos pipelines"

O histórico passa a explicar o que mudou e por que a mudança existe.

Publicar

Envie a branch para revisão no GitHub.

git push -u origin feature/pipelines-ingestao-metar

A branch remota fica disponível para abrir pull request.

Comando	Função
`git status`	Mostra arquivos modificados, adicionados, removidos e a branch atual.
`git pull --rebase origin main`	Atualiza sua branch local com a main remota, reaplicando seus commits por cima.
`git switch -c feature/pipelines-ingestao-metar`	Cria e entra em uma nova branch de trabalho.
`git add <arquivo>`	Seleciona arquivos para entrarem no próximo commit.
`git commit -m "feat: descreve a mudança"`	Registra um ponto de mudança com mensagem clara.
`git push -u origin feature/pipelines-ingestao-metar`	Publica a branch no GitHub e cria o vínculo com a branch remota.

6. Commits, Mensagens e Pull Requests

Commits devem representar unidades pequenas de mudança. Evite commits enormes misturando documentação, ajuste visual, experimento e refatoração. Quando o histórico é claro, fica mais fácil revisar, reverter e entender decisões meses depois.

Para mensagens, use um formato inspirado em Conventional Commits: tipo: descrição curta. A descrição deve responder o que mudou, não apenas onde mudou.

Tipos recomendados

feat: nova DAG, endpoint, tela, consulta ou capacidade.
fix: correção de bug em pipeline, portal, ontologia ou validação.
docs: documentação do portal, README, guia ou referência.
refactor: reorganização sem mudar comportamento operacional.
test: testes, fixtures ou massa de validação de dados.
chore: manutenção, build, dependências ou configuração.

git add src/app/git-guia/page.tsx src/data/search.ts
git commit -m "docs: adiciona guia de git para pesquisadores"

Pull request bem escrito

Ao abrir um pull request, descreva o objetivo, liste o que foi alterado, indique como validar e sinalize riscos conhecidos. Para pesquisa, inclua também origem dos dados, hipótese testada ou relação com experimento quando isso for relevante.

Exemplo: alterações em ita-airdata-pipelines devem dizer qual fonte ou DAG foi afetada; mudanças em ita-airdata-ontology devem apontar quais conceitos, classes ou relações foram revisados.

Objetivo da mudança em uma frase.

Repositório, DAG, rota, ontologia ou serviço afetado.

Como validar localmente ou em ambiente de teste.

Riscos conhecidos, limitações e próximos passos.

7. Entender Semantic Versioning

Semantic Versioning, ou SemVer, é um padrão para comunicar o impacto de uma versão. O formato é MAJOR.MINOR.PATCH, por exemplo 1.4.2. Ele ajuda pesquisadores e operadores a saber se uma atualização é apenas correção, nova capacidade ou mudança que exige cuidado.

No AirData, essa leitura é útil para releases do portal técnico, dos pipelines, da ontologia e de serviços como qualidade de dados ou RAG. Mesmo quando o projeto ainda não publica releases formais, pensar em SemVer ajuda a classificar impacto e risco da mudança.

MAJOR

Mudança incompatível

Exemplo: 2.0.0

Use quando uma alteração quebra contratos existentes, remove campos, muda APIs ou exige migração manual.

MINOR

Nova capacidade compatível

Exemplo: 1.4.0

Use quando adiciona funcionalidade mantendo compatibilidade com o que já existia.

PATCH

Correção compatível

Exemplo: 1.4.2

Use para bugfix, ajuste de texto, melhoria pequena ou correção operacional sem mudança de contrato.

Situação	Versão antes	Versão depois	Motivo
Correção de texto no portal ou bug pequeno no quality-check	1.2.0	1.2.1	PATCH
Nova DAG nos pipelines ou nova seção no portal compatível	1.2.1	1.3.0	MINOR
Alteração que quebra schema AirData, DAG ou contrato de API	1.3.0	2.0.0	MAJOR

8. Comandos Essenciais por Situação

Leitura e diagnóstico

git status: Estado atual do repositório.
git log --oneline --decorate --graph -n 12: Histórico curto e visual.
git diff: Diferenças ainda não adicionadas ao commit.
git diff --staged: Diferenças já preparadas para commit.
git remote -v: Endereços remotos configurados.

Branches

git branch: Lista branches locais.
git branch -a: Lista branches locais e remotas.
git switch main: Troca para a branch main.
git switch -c docs/airdata-guia-git: Cria e entra em nova branch.
git branch -d nome-da-branch: Remove branch local já mesclada.

Sincronização

git fetch --all --prune: Busca novidades e remove referências remotas antigas.
git pull --rebase origin main: Atualiza a branch local a partir da main remota.
git push: Envia commits da branch atual.
git push -u origin nome-da-branch: Publica branch nova e define upstream.
git push --delete origin nome-da-branch: Remove branch remota quando não for mais necessária.

Correções seguras

git restore <arquivo>: Descarta mudanças locais não commitadas em um arquivo.
git restore --staged <arquivo>: Remove arquivo da área de stage sem apagar a mudança.
git commit --amend: Ajusta o último commit local antes de publicar.
git revert <hash>: Cria um novo commit que desfaz um commit anterior.
git stash push -m "mensagem": Guarda mudanças temporariamente sem commit.

9. Problemas Comuns e Como Resolver

Antes de desfazer algo

Comandos como git restore, reset e limpeza de arquivos podem apagar trabalho local. Quando houver dúvida, salve um commit temporário ou use git stash antes de tentar corrigir o estado do repositório.

Problema	O que significa	Caminho seguro
Tenho mudanças locais e preciso atualizar	O Git pode bloquear o pull para não sobrescrever arquivos.	Faça commit se a mudança estiver pronta, ou use `git stash push -m "trabalho temporario"`.
Adicionei arquivo errado ao stage	O arquivo entrou na preparação do commit.	Use `git restore --staged <arquivo>`.
Quero desfazer uma mudança não commitada	O arquivo local está diferente do último commit.	Use `git restore <arquivo>` apenas se tiver certeza de que pode perder essa mudança.
Minha branch ficou atrás da main	Outras mudanças chegaram antes da sua.	Rode `git fetch origin` e depois `git rebase origin/main` na sua branch.
Conflito de merge ou rebase	Duas pessoas alteraram a mesma região de código ou texto.	Abra os arquivos marcados, escolha a versão correta, teste, faça `git add` e continue o rebase ou merge.

10. Boas Práticas para o AirData

Antes de começar

Leia o README do repositório afetado, como ita-airdata-pipelines, ita-airdata-ontology, ita-airdata-rag-system-llm ou ita-airdata-quality-check.
Atualize a main antes de criar branch.
Defina se a mudança é feature, fix, docs, chore ou experimento.
Prefira mudanças pequenas e revisáveis.

Antes de abrir PR

Rode testes, build ou validação disponível no projeto.
Revise git diff para evitar arquivos acidentais.
Escreva descrição clara do objetivo e do impacto.
Informe limitações, dados usados, DAGs afetadas, conceitos de ontologia alterados ou rotas do portal envolvidas.

Regra de ouro: se outra pessoa precisar entender sua mudança no futuro, o nome da branch, a mensagem do commit e o pull request devem contar a mesma história.