Descrevendo e criando issues como um profissional
Tags: braziliandevs, github, management, productivity
Published: 2023-08-17 03:15:01

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](#introdução)
1. [Descrevendo issues como um profissional](#descrevendo-issues-como-um-profissional)
1. [Utilizando templates para criar issues](#utilizando-templates-para-criar-issues-como-um-profissional)
1. [Exemplo de template](#exemplo-de-template)
1. [Exemplos no mundo real](#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](https://dev.to/compjunior/documentando-o-desenvolvimento-com-issues-32ki), 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](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/awsjka330hwqnxh8fj8q.png)

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

    ![Seção features no GitHub](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/xz8tphkyortvxp81b8cx.png)

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](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/m4mtw6v85rncv7gsgmlx.png)

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](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/9r2pmce46udzj92lintw.png)



## Exemplo de template

```markdown
## 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]

```

## Exemplos no mundo real

### [React](https://github.com/facebook/react/)
- Issue de bugs:
![Preview do template de issue do tipo bug no repositório do React](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/cs7maq7a85dmey233c75.png)

### [FreeCodeCamp](https://github.com/freeCodeCamp/freeCodeCamp)
- Issue do freeCodeCamp para entregar desafios de código da plataforma
![Issue do freeCodeCamp para entregar desafios de código da plataforma](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/j1gtd6jmdavw7q00uyc1.png)


## 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](https://dev.to/compjunior/o-que-e-uma-empresa-junior-jdi)) 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](https://compjunior.com.br)!
- Ou, se preferir, acesse nosso [Instagram](https://compjunior.com.br)!