Template de solicitação de recurso que vira changelog
6 min de leitura
Um template de solicitação de recurso é um formulário com quatro perguntas: o que a pessoa está tentando fazer, o que a impede, o que ela tentou em vez disso, e como ela quer ser avisada quando estiver pronto. Tudo mais que geralmente aparece em um, seletores de prioridade, estimativas de esforço, pontuações de valor de negócio, é para a equipe que recebe a solicitação, e é preenchido incorretamente por quem envia.
Solicitações organizadas são o teste errado para um template. O certo: seis meses depois, quando o recurso é lançado, alguém consegue encontrar a solicitação, entendê-la, e avisar a pessoa que a escreveu? A maioria dos templates é desenhada para admissão. Este é desenhado para o dia em que o ciclo fecha.
O que um template de solicitação de recurso deveria incluir?
Deveria incluir o objetivo, o bloqueio, a solução alternativa, e um caminho de volta para quem pediu. Quatro campos, nessa ordem, cada um responde a uma pergunta que a equipe fará depois.
| Campo | A pergunta que responde depois | Por que está no formulário |
|---|---|---|
| O que você está tentando fazer? | O recurso construído era o que era necessário? | O objetivo sobrevive a qualquer proposta concreta |
| O que te impede hoje? | Como é “pronto”? | Nomeia a lacuna sem prescrever a correção |
| O que você faz em vez disso? | Quão urgente isso é de verdade? | Uma solução alternativa dolorosa é um sinal mais forte que um seletor de prioridade |
| Como devemos te avisar? | Quem recebe a mensagem de “lançado”? | O campo que a maioria dos templates omite |
O que fica deliberadamente ausente: uma solução proposta como campo obrigatório (bem-vinda como comentário, errada como enquadramento), um seletor de prioridade (todo mundo que envia escolhe alta), e qualquer estimativa de esforço ou valor (trabalho da equipe, depois da triagem). Um template que pede uma solução recebe solicitações de botões; um template que pede um objetivo recebe solicitações de resultados, e sobre resultados é que se escreve uma entrada de changelog.
O template
Este é o template de issue do GitHub que usamos, como formulário. Cole-o em
.github/ISSUE_TEMPLATE/feature_request.yml e ele renderiza como formulário estruturado na página
de nova issue. Solicitações registradas através dele caem como issues com os mesmos campos das
registradas por um widget de feedback, o que importa para a próxima seção.
name: Feature request
description: What you are trying to do, and what stops you.
labels: ["feature-request"]
body:
- type: textarea
id: goal
attributes:
label: What are you trying to do?
description: >-
The outcome, not the button. "Export a month of invoices as one
PDF" beats "add a PDF export".
validations:
required: true
- type: textarea
id: blocker
attributes:
label: What stops you today?
description: >-
Where the product runs out. An error, a missing option, a limit.
validations:
required: true
- type: textarea
id: workaround
attributes:
label: What do you do instead?
description: >-
The spreadsheet, the script, the manual step. "Nothing, I gave
up" is a valid answer.
- type: input
id: contact
attributes:
label: How should we tell you when it ships?
description: >-
An email address, or leave blank to be notified only on this
issue.Dois detalhes fazem o trabalho. labels: ["feature-request"] significa que a solicitação é
classificada na criação em vez de esperar que alguém a triagem. E o último campo existe porque
“vamos te avisar” é uma promessa, e uma promessa precisa de um endereço.
Quais etiquetas uma solicitação de recurso deveria carregar?
Uma solicitação de recurso deveria carregar uma etiqueta para o que ela é, uma para quão urgente é, e uma para de onde veio. Três etiquetas, três eixos, e cada uma é lida por uma leitora diferente.
| Etiqueta | Valores | Quem lê |
|---|---|---|
| Tipo | feature-request, bug | Quem decide em qual fila ela entra |
| Prioridade | priority:low, priority:medium, priority:high | Quem planeja o próximo ciclo |
| Origem | from-widget, from-form, from-support | Quem mede de onde vêm as solicitações |
O widget aplica os dois primeiros eixos e from-widget quando registra um envio como issue;
from-form e from-support são sugestões para solicitações que chegam por outros caminhos. As
etiquetas do widget são um tipo (bug ou feature-request, decidido por um classificador só a partir da
mensagem), uma prioridade (um relato de falha calmo e específico é alto; um duplicado de algo já
perguntado é baixo; qualquer coisa que sequer sugira um problema de segurança é bug e alto,
independente da formulação), e from-widget. Os mesmos três eixos funcionam para solicitações que
chegam manualmente através do template acima, e esse é o ponto: uma solicitação é uma solicitação,
não importa por onde entrou.
Mais uma convenção: o widget remove o endereço de e-mail de quem enviou do corpo da issue antes de registrá-la, porque a issue vive em um repositório que pode ser público, e o substitui por uma referência de envio. O endereço fica fora da issue; quem enviou acompanha o resultado no próprio widget. Faça o mesmo com o campo de contato se seu tracker for visível para pessoas fora da equipe.
Como uma solicitação de recurso vira uma entrada de changelog?
Uma solicitação de recurso vira uma entrada de changelog quando um pull request fecha a issue e a
entrada redigida a partir desse pull request linka de volta. O mecanismo são as próprias
palavras-chave de fechamento do GitHub: uma PR cuja descrição diz Fixes #142 fecha a issue 142
no merge. Se suas entradas de changelog são redigidas a partir de pull requests mergeados, o
rascunho pode carregar o número da issue com ele, e a entrada sabe quem pediu.
Essa é a razão pela qual o template pede o objetivo em vez da solução. Quando a entrada é escrita, o objetivo é a frase de que quem escreve precisa: “Agora você pode exportar um mês de faturas como um único PDF” é uma entrada de changelog. “Adicionado export de PDF” é uma mensagem de commit. As ferramentas de changelog que redigem a partir de pull requests podem fazer a coleta e o link; a formulação ainda precisa de uma pessoa, e a pessoa precisa do objetivo.
O que acontece quando é lançado?
Quem pediu é avisado, com um link para a entrada. No nosso setup isso é automático para solicitações que chegaram pelo widget: um comentário dizendo “Shipped — <título da entrada>” com um link para a entrada publicada, postado na issue assim que uma pessoa aprova a entrada, enquanto o widget mostra a mesma entrada para quem enviou. Uma issue aberta manualmente a partir deste template não recebe comentário automático; feche esse ciclo você mesmo, pela mesma regra. O comentário é postado deliberadamente na aprovação em vez de no merge: um comentário dizendo que algo está no ar antes de estar é uma promessa quebrada com carimbo de tempo. Cada solicitação é notificada no máximo uma vez; uma segunda aprovação da mesma entrada não produz um segundo comentário.
Se vocês fazem isso manualmente, a mesma regra se aplica. Não fechem o ciclo pelo pull request. Fechem-no pela entrada publicada, e fechem uma vez. Feed e widget levam a mesma entrada para todo mundo que não pediu, que são a maioria; o comentário é para quem pediu.
Por que a maioria dos templates de solicitação de recurso falha
Eles são desenhados para facilitar a triagem e conseguem, ao custo do único momento que importa para quem pediu. Um template com doze campos recebe menos solicitações, e as que recebe vêm de pessoas com a paciência de preencher doze campos, o que não é a mesma população de quem precisa do recurso. Um template com quatro campos, um dos quais é “como te contatamos”, recebe mais solicitações e pode honrar todas elas.
FAQ
Um template de solicitação de recurso deveria perguntar sobre prioridade? Não. Pergunte sobre a solução alternativa em vez disso. “Eu exporto para uma planilha e redigito toda sexta-feira” diz mais sobre prioridade do que um menu suspenso que quem enviou marcou como alta.
Quem pede deveria propor uma solução? Pode, no texto livre. Não faça disso o enquadramento. Solicitações escritas como soluções são mais difíceis de fundir umas com as outras e mais difíceis de transformar em uma entrada de changelog.
Solicitações de recurso deveriam aparecer em um roadmap público? Uma vez planejadas, sim: uma etiqueta na mesma issue a coloca na coluna planejado, e quem pediu pode ver como ela se move. O artigo roadmap público é o mecanismo.
Como lidar com duplicatas?
Vincule a nova solicitação à issue existente e marque com prioridade baixa; não a feche. Cada
duplicata é mais uma pessoa para avisar quando for lançado. Com o comentário automático do
Changeloop, essa pessoa só é avisada se o pull request também nomear a issue dela
(Fixes #142, fixes #187).
Onde o template deveria viver? No repositório que vai receber o pull request, para que a palavra-chave de fechamento funcione. Uma solicitação em um tracker separado precisa ser vinculada manualmente no merge, e é esse o passo que é pulado.
As afirmações técnicas deste artigo não foram revisadas de forma independente. Se algo estiver errado, avise a gente e vamos corrigir.