Skip to content

Instantly share code, notes, and snippets.

@rondy
Last active March 2, 2021 11:28
Show Gist options
  • Save rondy/88c5f0a378e51dd55802 to your computer and use it in GitHub Desktop.
Save rondy/88c5f0a378e51dd55802 to your computer and use it in GitHub Desktop.

Rondy Sousa (@plataforma.rondy): @brunno.santos, puxando o gancho no papo das descrições de MR, uma coisa que a gente costuma fazer é manter a descrição do MR no commit principal (title+descripton do MR batendo com o do commit).

A vantagem é que a motivação/propósito do MR ("pois o bundle da product já tem esse link salvo no banco") fica documentada no histórico do controle de versão (e agnóstico da plataforma de code review).

Brunno dos Santos (@brunno.santos): @plataforma.rondy interessante esse esquema que vcs usam de colocar a descrição no commit, mas o problema é definir qual é o commit principal, as vezes nem temos um. Como vocês lidam com isso?

Rondy Sousa (@plataforma.rondy): @brunno.santos, A gente faz squash dos commits antes de fazer merge no master, com o commit resultante recebendo o título + descrição do MR.

Na grande maioria das vezes, commits separados representam (ou deveriam representar) apenas "snapshots" de work-in-progress do MR. No momento do merge, eles acabam não acrescentando muito valor co-existindo no baseline do master. Por exemplo, "Removes File.join to create an URL" foi um fix de um review que não precisa ser mencionado no futuro, então o squash dele é desejável (bem como omitir que ele sequer chegou a existir).

Algumas coisas "periféricas" valem ser mencionadas, entretanto. Nesse caso, eu costumo listá-los com bullet points, numa seção invisível "coisas que também aconteceram aqui e que você deveria saber" (importante que eles não fujam muito do objetivo do MR). Se existem muito commits que não fazem sentido estarem juntos, pode ser um sinal de que o MR está entregando muita coisa ("SRP de commit", talvez?). Em alguns MRs isso pode até acontecer e ser um cenário legítimo, claro (ex: MR que é um batch de pequenos fixes isolados).

(Toda essa "cerimônia" de preparação do commit acontece pouco antes de fazer o merge. Antes disso, o mantra "commit early commit often" é liberado).

TL;DR: MR e o commit mergeado deveriam representar a mesma coisa (semanticamente) pro controle de versão, sendo o MR apenas um meio pra se chegar no commit final, que foi evoluído coletivamente e que entregou um valor único pro projeto (me parece que o Linus Torvalds tem essa mesma pira).

Uma coisa que eu também costumo fazer é tentar mapear um MR/commit com um cenário de história de usuário, se você que pensar que o usuário da user story pode ser não apenas o "cliente final", mas qualquer outra entidade que interage com o software no sentido comportamental (um worker, uma abstração, um serviço) e que o commit por si deveria trazer apenas um benefício direto pro usuário (seguindo a lógica "se você reverte um commit, você deveria ter uma unidade de software resultante, não meio ou 1 e meio").

Vou tentar dar um exemplo prático:

US #1234
Feature:
  Como usuário do sistema
  Quero pode ver alguma coisa ABC
  Para que eu consiga obter um insight DEF dessa informação

Cenário: Usuário pode ver alguma coisa ABC
  Dado que eu...
  Quando...
  Então

👇

$ git ci

[Title] User can see something ABC

[Description] This aims to provide to users an insight DEF from the presented information.

👇

[código + cobertura de testes do aplicando a pirâmide de testes]

Seguindo esse flow, o "SRP do commit" vem naturalmente. Nem sempre dá pra fazer, mas quase sempre rola.

Dá pra incluir nesse raciocínio toda aquela promessa do BDD/DDD de desenvolver software outside-in, linguagem ubíqua, código que é a representação viva do domain model etc.

Informações que vem de uma descrição de US e que podem ser acrescentadas na descrição do commit (nem todo commit precisa de tudo isso):

  • O quê
  • Por quê
  • Pra quem
  • Coisas que foram feitas e voce deveria saber
  • Fora de escopo
  • How to
  • Referências externas

A maior vantagem que eu vejo disso aí é que o código resultante, e a forma como ele foi comunicado/introduzido, tem ligação direta com a forma como ele foi pensado/definido/planejado, fora que o histórico do git fica bem menos sujo e que o git vira mais um "diário" que um "baú de código".

Se quiser trocar mais ideia sobre o assunto pode me procurar outra hora em outro meio de comunicação.

Brunno dos Santos (@brunno.santos): @plataforma.rondy caraca man! Valew pelo conteúdo! :) Bom, eu entendi qual é o propósito e como vocês chegaram nessa conclusão, mas nosso fluxo está um pouquinho diferente, por exemplo: nós só fazemos squash quando um commit não está "completo", fora isso mantemos o histórico dentro da "curva" do branch mesmo. Acho que vale a pena levantar essa prática com o pessoal daqui pra decidir se vale aderir ou não. Nesse caso vou mergear assim mesmo, mas mesmo assim obrigado por todo o contexto, esse comment ta mais bem documentado do que o MR em si hehehe valew.

@georgeguimaraes
Copy link

Acho que vc tá querendo escrever um blog post hein

@FlaviaFortes
Copy link

☝️

@hugobarauna
Copy link

Lindo! ❤️ blog post 👍

@igorffs
Copy link

igorffs commented Sep 1, 2015

👏 ❤️

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment