Melhorando issues para ficarem mais amigáveis para iniciantes

Recentemente fiz uma autoanálise visando as issues que tenho aberto no training-center e me deparei com um cenário ruim: as issues que eu abro não são nem um pouco amigáveis para iniciantes. Não são descritas de maneira suficientemente boas. Não dá para alguém fora de contexto pegar a issue e resolver, antes disso ela teria que entrar no nosso Slack e perguntar lá os detalhes do problema.

Busquei uma melhoria e cheguei a algumas conclusões que listo aqui neste post para aperfeiçoar a maneira como descrevemos as issues para que qualquer pessoa em qualquer fase de conhecimento consiga resolver.

Alguns pontos importantes que fizeram diferença nas minhas issues: um título melhor, uma boa descrição e labels. Acompanhe meu raciocínio para entender e se tiver alguma dica legal, compartilhe comigo nos comentários.

Issues são extremamente importantes

As issues são uma importante feature das plataformas de armazenamento de código fonte, como o GitHub e GitLab. Com elas nós descrevemos os problemas que temos nos projetos para que sejam resolvidos por qualquer pessoa que quiser contribuir.

Elas existem para isso e somente isso, com exceções do pessoal que tem usado GitHub como plataforma para foruns e outras interações, como o code-review, frontendbr/forum, backendbr/forum.

Sempre que falamos para alguém começando a contribuir com open source dizemos para que olhe nas issues abertas para procurar problemas para solucionar. Muitas vezes a alteração que vamos fazer para resolver um problema já está sendo tratada/resolvida por outra pessoa e esta pessoa pode estar marcada em uma issue ou mesmo alguém já reportou o problema com mais informações que podem nos ajudar a criar uma melhor solução.

Título da issue

O título da issue precisa ser uma pré descrição do problema a ser solucionado.

Um exemplo de título ruim: olha o bicho vino! — o que seria isso, um bug monstro chegando em sua carruagem binária?

Nesta parte ainda tenho muito a melhorar, pois sou péssimo com títulos.

Normalmente adicionamos algo direto, mas sempre no imperativo.

Ex.:

• resolver bug x
• implementar tela y
• remover código bugado z

O ideal é que o título tenha relação lógica com o conteúdo da issue.

Melhorando as descrições

Na descrição da issue devemos imaginar que alguém que nunca viu nosso projeto, não sabe quem somos e nunca encostou em nosso código esteja lendo. Então ela precisa ser o máximo explicativa possível.

Exemplo de issue aberta no projeto mentoria onde eu disse que precisávamos reorganizar nosso board, porém na issue não está definido se é uma discussão, se já é uma implementação, que tipos de problemas serão resolvidos ou coisa do tipo

No exemplo acima, quem estava no nosso Slack sabe claramente o que precisávamos definir dessas labels, colunas e dados importantes no Trello.

Pra você, pessoa com experiência ou que já está inserida em nosso contexto, pode até parecer simples: é só pra definir algumas coisas que vão entrar no Trello. Porém a realidade é um pouco pior… O que de fato é necessário definir dessas labels? Que dados importantes seriam esses? Por que é necessário reorganizar o board? Quem está lendo pode mudar essas labels? Que board é esse?

Pensando nessas questões estou seguindo um padrão para a criação das minhas issues que é o seguinte:

• por que essa issue existe?
• que tipo de problema será resolvido com essa issue?
• o que já tentamos fazer
• como resolver essa issue? — caso já exista uma solução prévia
• que valor essa issue agrega?

Essas perguntas podem ajudar a pessoa que irá contribuir com o projeto e ainda pode evitar alguma discussão repetida no meio da issue, afinal pode aparecer alguém propondo alguma solução para o problema que já foi discutida previamente e que não é a solução ideal e teríamos que explicar tudo de novo.

Vou explicar um pouco mais cada ponto dos que citei.

Por que essa issue existe

Imagina que você acabou de conhecer o projeto e encontra uma issue:

• resolver bug x

O por que dela existir está meio claro no título da issue, certo?

Resolver um bug.

Pode ser que não.

Uma pessoa fora de contexto pode imaginar: o que diabos acarretou esse bug, como eu começo a procurar esse bug, será que já tentaram alguma coisa para resolver isso?

Então seria bom colocarmos algo do tipo:

Recentemente fizemos uma mudança na funcionalidade X e de repente começou a disparar o erro Y.

Isso contextualiza a pessoa que vai pegar o problema a ser resolvido. Ela já saberá que deve buscar algo relacionado a funcionalidade x. A pessoa já entra no problema pensando em testar a funcionalidade x para ver o que acontece, como ela se comporta, onde e o que debugar.

Que tipo de problema será resolvido com essa issue

Essa questão é mais mental do que descrita no texto que encorpora a issue. Devemos fazer uma análise do que escrevemos e pensar:

• ficou entendido que isso aqui é um bug a ser solucionado e a pessoa já pode pegar pra resolver?
• está claro que nessa issue estamos somente definindo como fazer algo e não já sair implementando?
• ficou entendido que isto aqui é uma feature que já pode ser implementada?

Imagine que durante a definição de uma possível solução para um problema alguém pode pegar e já sair desenvolvendo. Isso irá gerar uma frustração imensa na pessoa caso mudemos o requisito no meio do desenvolvimento. Pior, se ao final das discussões percebermos que nem é mais necessário a implementação dessa funcionalidade e todo o trabalho da pessoa foi jogado fora.

As coisas devem estar claras.

O que já tentamos fazer

O processo todo pode ser agilizado com uma descrição de o que já tentamos fazer para solucionar um problema.

Imagina que nosso projeto possua um formulário de cadastro que ao ser enviado exibe uma notificação de “cadastro realizado com sucesso” e você encontrar a seguinte issue no repositório:

• corrigir validações do formulário de cadastro

Isto abre um leque de possibilidades na nossa mente. Pode ser um problema no front, pode ser no back-end, pode ser qualquer coisa.

Se alguém já fez uma análise prévia de logs do servidor pode falar se o problema é no back-end, por exemplo. Isso já evita um trabalho de análise e agiliza a resolução da issue.

Como resolver essa issue

Este é o ponto onde ajudamos a pessoa iniciante.

Adicionando uma sessão “como solucionar este problema” e os possíveis passos lógicos de como resolver, até mesmo uma dica exata do que fazer, pode ser o ponta pé que falta para a pessoa contribuir no nosso projeto.

Isso não é importante somente para projetos open source. Em seu trabalho você pode ter alguém iniciante que muitas vezes olha uma issue, não faz ideia de como resolver aquilo e não tem ninguém disponível para ajudar ela no momento em que ela está analisando o problema.

Nos testes que eu fiz, adicionei uma descrição amais que foi o “como solucionar”:

Issue com uma descrição do problema e uma sessão de “como solucionar” informando os passos lógicos para encontrar o problema e uma dica de como resolver

E o feedback da Raquel Luz foi muito positivo! ;D

A maioria das vezes não sabemos como solucionar um problema ao abrir uma issue. Porém, em casos esporádicos, pode acontecer da solução estar na nossa mente e não temos tempo para parar para resolver (principalmente quando se trata de open source), então é só adicionar ali.

Que valor essa issue agrega

Este ponto é muito interessante.

Quando as pessoas não entendem o valor que será agregado com a resolução de um problema elas podem simplesmente não sentir vontade de fazer aquilo. Elas não veem propósito em gastar seu tempo resolvendo aquela issue.

Isso pode acarretar diversos problemas como alguém resolver um problema de qualquer jeito e o trabalho ser ainda maior no code review, alguém ler a issue, não se interessar e simplesmente ignorar e qualquer outro problema relacionado a motivação no desenvolvimento de software.

A maneira de demonstrar o valor agregado é colocando o retorno que essa issue pode trazer.

Ex.:

Resolvendo essa issue as pessoas irão parar de clicar em um link que não leva a lugar nenhum, diminuindo o ódio que elas sentem pelo nosso site

Conclusão

Todos os pontos levantados podem ser escritos no meio da issue ou simplesmente serem um checklist mental na hora de escrever a descrição. Você quem decide.

Se for utilizar estes pontos no meio da issue, recomendo criar um issue_template.md.

Um exemplo de issue no modelo antigo:

Criar um FAQ para o projeto · Issue #801 · training-center/mentoria

Agora outro exemplo no modelo novo:

times[code-review] · Issue #41 · training-center/sobre

Pode parecer muito mais trabalhoso, porém é muito mais ágil para umtime a segunda issue.

Leia mais artigos meus em:

Meu site pessoal

iMasters