Escrever uma boa descrição de Pull Request é uma das tarefas mais tediosas que um desenvolvedor precisa fazer. E às vezes pode parecer contraproducente.

Mas desenvolver essa habilidade vai longe e realmente ajuda seus stakeholders e sua organização a longo prazo.

Portanto, é sempre melhor investir 10 minutos extras hoje, em vez de quebrar a cabeça 6 meses depois, tentando explicar por que você fez o que fez.

O artigo a seguir explica as diferentes partes de uma descrição de solicitação pull e por que você deve incluí-las.

O que é uma descrição de RP?

Uma descrição de solicitação pull descreve o que constitui a Solicitação Pull e quais alterações você fez no código.

Ele explica o que você fez, incluindo quaisquer alterações de código, alterações de configuração, migrações incluídas, novas APIs introduzidas, alterações feitas em APIs antigas, quaisquer novos workers / crons introduzidos no sistema, alterações de cópia e assim por diante. Você captou a essência.

Você deve incluir esta seção porque ela dá uma ideia para os diferentes interessados ​​sobre o que o RP está fazendo.

Para uma pessoa não técnica, a descrição deve explicar qual será o impacto no sistema quando essas alterações de código forem implantadas na produção.

Também ajudará o revisor a entender o que estará revisando (uma espécie de prólogo / trailer).

E, finalmente, ajuda QA / SDET a entender o escopo do PR também.

Portanto, o “o quê” do PR deve dar uma ideia do que constitui as mudanças no PR.

A seção “Por que”

Esta seção explica por que as alterações acima explicadas foram feitas.

Às vezes, um desenvolvedor acha que não há problema em escrever “Requisito de negócio / produto” na descrição. Tudo bem, mas isso anula o propósito desta seção.

Se houver uma explicação melhor para o motivo das mudanças sugeridas, é sempre bom anexar um link de referência do documento para essas informações. Uma boa seção “Por que” deve explicar o raciocínio por trás de todas as mudanças.

Você deve incluir esta seção porque ela explica por que você sugeriu suas alterações. Pode não parecer razoável incluir esta seção em um prazo mais curto, mas ela desempenha um papel vital à medida que o produto amadurece e se estende por anos.

Os desenvolvedores / pessoal do produto vêm e vão, mas o código permanece. E quando um novo desenvolvedor trabalha em um trecho de código e encontra uma discrepância nele, ele pode cavar mais fundo e chegar à solicitação pull de 2 anos atrás que fez essas mudanças.

Um bom “porquê” fornece a explicação e as suposições feitas naquele momento.

CTO de GoJek uma vez explicou que eles não desafiam seu código legado e não questionam por que parece haver algum recurso de aparência absurda no produto.

Eles apenas voltam e verificam a documentação.

As suposições e circunstâncias podem ter mudado e, portanto, o código evolui. O que parece bastante absurdo hoje pode ter sido relevante há 2 anos. Portanto, é melhor explicar hoje por que você está fazendo uma mudança específica.

Escopo de Teste

Esta seção deve incluir uma lista de cenários em que você precisa ficar de olho ao testar este PR específico. (Isso incluirá fluxos, APIs, crons, trabalhadores e assim por diante.)

Um bom escopo de teste dá visibilidade à equipe de QA / SDET sobre os cenários e fluxos que eles precisam testar.

Também pode ajudá-lo enquanto escreve esta seção. Eu mesmo encontrei problemas, o que me levou a voltar à fase de desenvolvimento e testá-los novamente.

Um escopo de teste totalmente escrito ajuda os desenvolvedores a testar o PR com mais eficiência e fornece uma imagem completa do PR para a pessoa que o testa.

Documentos relevantes)

Esta seção inclui qualquer documento relevante que precise ser anexado à descrição de RP.

Isso pode incluir documentos de requisitos do produto, diagramas de arquitetura, diagramas de sistema de banco de dados, padrões de design usados, diagramas de classe, documentação de biblioteca externa e assim por diante.

Esta seção ajuda a explicar quaisquer suposições e referências feitas ao trabalhar nesta solicitação de recurso. E isso desempenha um papel importante no longo prazo.

Quando alguém volta e vê por que essa mudança foi sugerida, a seção de documentos relevantes o levará à documentação específica para que possam entender o problema claramente. Ou pode levá-los aos detalhes técnicos de implementação do cenário no momento do desenvolvimento.

PR (s) dependente (s) (se houver)

Às vezes, um recurso específico se estende por vários repositórios do GitHub e é importante liberá-los em uma determinada ordem.

Por exemplo, você pode precisar implantar um repo antes de outro ou pode precisar implantá-los lado a lado.

Seja qual for o caso, esta seção explica qualquer código dependente em que este PR depende.

Você deve incluir esta seção porque ela realmente ajuda o implantador a entender a ordem de implantação. Se o código de outro repo precisar ir primeiro, o implantador entrará em contato com a pessoa responsável pela implantação do outro repo para garantir que a implantação aconteça primeiro. No geral, ajuda a suavizar o processo de implantação.

Mudanças de configuração (se houver)

Esta seção deve incluir todas as alterações de configuração que precisam ser adicionadas aos segredos antes que o PR seja implantado na produção.

Haverá momentos em que o implantador mesclará 10-20 PRs por vez e será difícil para eles acompanhar todas as alterações de configuração.

Por causa disso, é sempre melhor incluí-los na seção de mudanças de configuração. (Não coloque as chaves secretas lá, apenas inclua os nomes das chaves e como obtê-las.)

Eles são muito importantes na descrição de uma solicitação pull e transmitem muito significado quando a equipe cresce.

A seguir estão algumas tags que eu uso, mas você pode adicionar tags diferentes de acordo com suas necessidades.

  • Dev Concluído – Quando o desenvolvimento for concluído pelo lado do desenvolvedor.
  • Auto-revisado – Quando o (s) desenvolvedor (es) do Pull Request tiverem revisado o Pull Request de seu lado e puderem entregá-lo a seus pares para uma Revisão por Pares.
  • Auto-testado – Quando o (s) desenvolvedor (es) da Solicitação Pull tiver testado as alterações por conta própria de acordo com a descrição fornecida na seção Escopo de teste.
  • Mudanças de configuração – Esta tag indica que há algumas mudanças de configuração que precisam ser feitas antes de implantar o PR para produção. (Isso inclui chaves secretas que precisam ser colocadas no sistema.)
  • Contém migração (ões) – Isso indica que o PR contém uma migração. Se for uma migração de longa duração, ela deve ser especificada com antecedência.
  • Lançamento pronto – Isso indica ao implantador que o PR está pronto para implantação e será selecionado pelo implantador no próximo ciclo de implantação.
  • Revisado por pares – Quando o Par tiver revisado o PR e as alterações sugeridas forem feitas pelo (s) desenvolvedor (es). Isto é apresentado pelo Par que revisou o PR.
  • Testado pelo controle de qualidade – Isso indica que o QA / SDET testou o PR e é bom ser implantado em produção.

Conclusão

Neste artigo, examinamos as diferentes partes de uma descrição de RP. A maioria dos PRs que você faz não precisa de todas essas seções e tags, mas você deve tentar incluir o maior número possível.

Escrever esta descrição pode não parecer produtivo no momento em que você cria um PR, mas pode definitivamente ser útil no futuro.

Uma nota final: o acima exposto é minha opinião e pode diferir de sua perspectiva. Mas desenvolvi essa estratégia ao longo dos anos e ela contém a contribuição e a experiência de muitas pessoas com quem trabalhei na indústria. Portanto, você pode se sentir bem sabendo que ele foi testado em alto nível.



Fonte