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.
Acho que vc tá querendo escrever um blog post hein