DEV Community

Gustavo for Comp Júnior

Posted on • Updated on

Descrevendo e criando issues como um profissional

Domine a arte de criar descrições profissionais de problemas no GitHub! Este post revela como usar templates de issues para agilizar a documentação de bugs, incluindo elementos-chave como ambiente, comportamento esperado, passos para reproduzir e soluções.

  1. Introdução
  2. Descrevendo issues como um profissional
  3. Utilizando templates para criar issues
  4. Exemplo de template
  5. Exemplos no mundo real

Introdução

Esse é o segundo post da série falando sobre issues e GitHub Projects. Já expliquei sobre as issues no primeiro post, recomendo que comece por ele.

Agora vou focar na descrição das issues e mostrar uma forma mais automatizada de criar issues.

Descrevendo issues como um profissional

  • Dados do Ambiente: Este é o contexto em que o problema ocorre. Pode incluir a versão do software, versão do sistema operacional, dependências relevantes e qualquer outra informação relevante.
  • Comportamento Esperado: O que você achava que o software faria ou deveria fazer.
  • Comportamento Real: O que o software está realmente fazendo. Aqui é onde você detalha o problema.
  • Passos para Reproduzir: Um guia passo a passo para recriar o problema.
  • Imagens/Capturas de Tela: Ajudas visuais para ilustrar o problema ou a sua ideia.
  • Registros de Erro: Os famosos logs, se disponíveis, podem fornecer informações valiosas sobre o problema.
  • Possível Solução/Sugestões: Ideias ou sugestões que possam ajudar a resolver o problema.

Utilizando templates para criar issues como um profissional

Agora que você já sabe como descrever as issues de forma profissional, é hora de dar um passo adiante e otimizar ainda mais o processo, tornando-o mais consistente e eficiente. Uma ótima maneira de fazer isso é utilizando templates para criar issues no GitHub.

Vantagens de usar templates de issues

  • Padronização: Os templates garantem que todas as issues sigam um formato consistente, o que facilita a compreensão por parte de todos os envolvidos no projeto.

  • Informações Relevantes: Com campos específicos para o ambiente, comportamento esperado, comportamento real e outros detalhes importantes, os templates ajudam a capturar as informações necessárias para uma análise eficiente do problema.

  • Economia de Tempo: Ao criar issues a partir de templates, você economiza tempo ao não precisar pensar repetidamente em quais informações incluir. Isso acelera o processo de documentação e resolução de problemas.

Como criar e usar templates de issues

  1. Acesse as Configurações do Repositório: No GitHub, vá até o seu repositório e clique na aba "Settings".

    Aba do repositório do GitHub

  2. Desça até a seção "Features" e clique em "Set up Templates"

    Seção features no GitHub

  3. Depois disso, você pode escolher o tipo de issue mais usuais: Bug, Feature. Ou você pode criar um template customizado para outro propósito em "Custom template"

    Tela de seleção de tipo de template de issue

  4. Preencha o Template: Quando você cria uma nova issue, você terá a opção de escolher um template e preencher os campos correspondentes. Isso garante que todas as informações relevantes sejam inseridas de maneira organizada.

  5. Quando terminar, não se esqueça de salvar as alterações ao clicar no botão "Propose Changes". Aparecerá uma tela para aplicar as alterações no repositório por meio de um commit, é só especificar a mensagem e fazer o commit clicando em "commit changes"!

    Formulário de commit antes de salvar as issues

Exemplo de template



## Descrição do Problema

[Descreva aqui o problema de maneira sucinta]

### Dados do Ambiente

-
Versão do Software: [inserir versão]
- Versão do Sistema Operacional: [inserir versão]
- Dependências Relevantes: [listar dependências, se aplicável]

### Comportamento Esperado

[Descreva aqui o comportamento que era esperado]

### Comportamento Real

[Descreva aqui o comportamento observado]

### Passos para Reproduzir

1.
[Descreva o primeiro passo]
2. [Descreva o segundo passo]
3. [E assim por diante...]

### Imagens/Capturas de Tela

[Insira imagens ou capturas de tela para ilustrar o problema]

### Registros de Erro

[Inclua logs ou mensagens de erro relevantes]

### Possível Solução/Sugestões

[Tenha espaço para ideias ou sugestões para resolver o problema]

Enter fullscreen mode Exit fullscreen mode




Exemplos no mundo real

React

  • Issue de bugs: Preview do template de issue do tipo bug no repositório do React

FreeCodeCamp

  • Issue do freeCodeCamp para entregar desafios de código da plataforma Issue do freeCodeCamp para entregar desafios de código da plataforma

Conclusão

Dominar a arte de descrever issues de maneira profissional e aproveitar os templates do GitHub é fundamental para um gerenciamento eficiente de projetos. Essas práticas não apenas aprimoram a comunicação, mas também impulsionam a resolução de problemas de forma estruturada e colaborativa. À medida que você avança em sua jornada de desenvolvimento, lembre-se sempre de aplicar esses conhecimentos para alcançar resultados mais sólidos e produtivos!

A Comp Júnior!

A Comp Júnior é uma EJ (não sabe o que é? Então clique aqui) que atua no mercado de tecnologia há mais de 20 anos em Lavras e região, prestando serviço de desenvolvimento web, mobile e multiplataforma.

Nossa missão é oferecer a transformação digital aos nossos clientes, expandindo os seus negócios para o mercado digital e alcançando um potencial desconhecido.

  • Se você quer saber mais, acesse nosso site!
  • Ou, se preferir, acesse nosso Instagram!

Top comments (15)

Collapse
 
ofelipexis profile image
Felipe Mendes

Ótimo post!

Collapse
 
kvnol profile image
Kevin Oliveira

sensacional!!!

Collapse
 
ilonavarro profile image
Ilo Navarro

Excelente!

Collapse
 
renanvidal profile image
Renan Vidal Rodrigues

excelente conteudo

Collapse
 
franolv profile image
Franciele B. de Oliveira

Vou usar pra ontem as dicas que vc deu! obrigada pelo conteúdo

Collapse
 
artenlf profile image
Luís Felipe Arten

Tópico mega importante! Muita gente não dá a devida atenção ao tema. Parabéns, primo!! E já deixei salvo aqui para poder compartilhar futuramente.

Collapse
 
dantas profile image
Gustavo

Perfeito primo, muito obrigado!!

Collapse
 
danielhe4rt profile image
Daniel Reis

Ótimo template pra issues e dicas sensacionais, primo!

Continue os posts que tá dahora d+!

Collapse
 
rudijr profile image
Rudi

ótimo conteudo

Collapse
 
codefriendship profile image
Augusto Cesar

Muito bom o conteúdo, primo!

Collapse
 
brunofndes profile image
Bruno Fernandes

mto bom post!