DEV Community

loading...
Cover image for Git commit, uma abordagem documental

Git commit, uma abordagem documental

wanderleyfa profile image Wanderley ・3 min read

git init

Utilizar um sistema de controle de versão, seja para códigos fontes de software, seja para documentos e imagens, é mandatório, seja para armazenar o código fonte de um software que pode render milhões, as fotos das últimas férias ou os recibos de pagamento de contas.
Neste texto eu vou abordar o versionamento de códigos fontes, utilizando o GIT como ferramenta.

Mas antes preciso agradecer ao Ishan Makadia por ter simplificado isso em um texto que me fez enxergar o commit como uma ferramenta poderosa de documentação.

Thank you very much Ishan Makadia, for making me think of commits as something documentary for the project, and not just as a reference. And because it allows you to use your text as a reference and be able to locate it for the Portuguese.

Contexto

O que vou citar abaixo são orientações, não regras que devem ser seguidas a risca. Mas são orientações que podem facilitar muito o trabalho da equipe como um todo, facilitando o controle semântico de versões, facilitando a geração automática de arquivos de CHANGELOG , fechamento automático de tarefas, entre outras ações que podem e devem ser automatizadas, facilitando assim todo o trabalho da equipe.

Citando o Conventional Commits 1.0.0 sobre uma mensagem de commit

A especificação do Conventional Commits é uma convenção simples para utilizar nas mensagens de commit. Ela define um conjunto de regras para criar um histórico de commit explícito, o que facilita a criação de ferramentas automatizadas baseadas na especificação. Esta convenção se encaixa com o SemVer, descrevendo os recursos, correções e modificações que quebram a compatibilidade nas mensagens de commit.

Resumindo : as mensagens de commit devem ser uteis o suficiente para documentar as alterações de código e serem parâmetros para que ferramentas de automação, integração, e/ou versionamento semântico possa se orientar e executar suas funções com base nessas mensagens.

Um bom commit

Por mais que parece um trabalho a mais, descrever bem um commit, um Pull Request ou um Merge Request, é uma prática que faz com que você sempre pense o seu código para o próximo desenvolvedor da equipe, que pode ser você mesmo ou alguém que jamais olhou aquele código mas que precisa corrigir algo em produção, e o seu commit pode economizar muito tempo de leitura de código e debug.

A estrutura de um commit pode se assemelhar a essa

<tipo>[escopo opcional]: <descrição>

[corpo opcional]

[rodapé(s) opcional(is)]
Enter fullscreen mode Exit fullscreen mode

Que, para exemplo, poderia se assemelhar a

fix: corrige pequenos erros de digitação no código

veja o ticket para detalhes sobre os erros de digitação corrigidos

Revisado por: Desenvolvedor Responsável
Refs #133
Enter fullscreen mode Exit fullscreen mode

Onde

  • < tipo > : o fato gerador desse commit, pode ser uma correção (fix), uma funcionalidade nova(feat), entre outros, como por exemplo @commitlint/config-conventional (baseado na Convenção do Angular) recomenda-se build:, chore:, ci:, docs:, style:, refactor:, perf:, test:, entre outros.
  • [escopo opcional] : quando se tem a necessidade de demonstrar algo que foi feito especificamente em um domínio que afete todo o software, como por exemplo idiomas, veja no exemplo abaixo
feat(lang): adiciona internacionalização
Enter fullscreen mode Exit fullscreen mode
  • : onde se pode descrever brevemente, sobre a mudança efetuada ou a nova funcionalidade implementada. Neste use sempre minúsculas, sem ponto ao final e os verbos no imperativo.
  • [corpo opcional] : o corpo seria um texto mais detalhado sobre o que foi desenvolvido, e como isso pode impactar em alguma área do sistema ou uma orientação de como encontrar mais informações.
  • [ rodapé(s) opcional(is)] : os rodapés servem para que se possa colocar informações utilizadas pelas ferramentas de automação para gerar CHANGELOGs, auto finalizar tarefas, iniciar rotinas de testes unitários, e integrações continuas

git push

Sei que o que falei aqui foi muito superficial em relação ao real cenário que cada um pode encontrar em sua equipe ou ambiente de trabalho, mas espero que esse texto possa te instigar a pesquisar mais sobre o assunto.

As referencias se encontram em links no texto, e logo abaixo

Referências:

Discussion (0)

Forem Open with the Forem app