Documentação de Boas Práticas Git

Objetivo

A ideia é padronizar os repositórios dentro do git para facilitar o entendimento entre os membros do time. Garantindo organização, velocidade e colaboração mais eficiente.

Configuração Inicial

Sempre antes de começar a desenvolver em um repositório, faça a configuração inicial do seu ambiente. A ideia é evitar commits Sempre usuário. Para isso, faça:

  git config --global user.name "Seu Nome"
git config --global user.email "seu.email@empresa.com"

Documentação

Toda vez que um projeto novo for iniciado, é necessário a criação de um arquivo README.md para documentar o objetivo, as funções e os detalhes do projeto.

Um exemplo de estrutura é:

Exemplo de README

Nomeação de Branches

A nomenclatura das branches nos ajudam a criar um fluxo de desenvolvimento consistente, de modo que toda nova branch serve a um propósito e após sua implementação deixa de existir. Devemos criar da seguinte maneira:

  • main: Versão estável do projeto, pronto para rodar em produção.
  • develop: Versão de desenvolvimento contínuo, onde as features se concentram.
  • feature/*: Novas funcionalidades
  • bugfix/*: Correções de funcionalidades implementadas.
  • release(opcional): Versão para preparação do deploy, usado com clientes.

Um exemplo de projeto com llm, seria:

  * main
│
├── develop
│   ├── feature/implementacao-rag
│   ├── feature/document-parser
│   ├── feature/interface-web
│   ├── feature/api-call
│   ├── bugfix/error-404-api
│   ├── bugfix/missing-documents
│   └── release/1.0.0

Commits

1. Frequência de commits

Evite fazer commits com grandes alterações e com mensagens genéricas. Pequenos commits frequentes facilitam o entendimento e correção em caso de bugs.

Faça commits a cada pequena mudança.

2. Mensagem de commit

A mensagem de commit deve ser breve, porém devemos conseguir identificar o motivo/funcão dela.

Recomendamos a seguinte estrutura:

  <tipo>: descrição breve

Onde, os tipos possíveis são:

  • feat: Nova funcionalidade
  • fix: Correção de bugs
  • docs: Mudanças documentação
  • refactor: Refatoração de código
  • test: adição/correção de testes.

Então, alguns exemplos de commit são:

  feat: consumo de documentos em pdf

feat: criação de embedding de documentos

fix: correção de bug na conexão com storage

refactor: padronização de acordo com pep8

Pull Requests

Toda atualização na main deve ser feito atráves de Pull Requests. Ela deve ter uma descrição clara do que foi feito e de preferência ser revisada por outra pessoa(reviewer).

Se possível, criar testes automatizados para testar que o comportamento geral do código não quebrou.

Boas práticas gerais

  • Sempre use .gitignorepara ignorar arquivos temporários ou ambiente virtual.
  • NUNCA commite .env, .pem ou arquivos com senhas hardcoded.

Referências

Conventional Commits

Git Flow