Documentando o desenvolvimento com issues
Tags: braziliandevs, git, github, management
Published: 2023-08-15 18:58:01

## Conteúdos

1. [Introdução](#introdução)
1. [O que é uma Issue](#o-que-é-uma-issue)
1. [A anatomia de uma issue](#a-anatomia-de-uma-issue)
1. [Acompanhando uma issue](#acompanhando-uma-issue)
1. [Conclusão](#conclusão)
1. [Links e referências](#links-e-referências)

## Introdução

Quero bater um papo sobre algo que está sempre presente no nosso dia a dia, mas nem sempre damos a devida atenção: o mundo do GitHub. Se você já passou pela situação de olhar para um código que fez há meses e se perguntar "O que diabos eu estava pensando aqui?", então, meu amigo, este post é para você!

Muitas vezes nos pegamos focados no ato de codar, implementar, criar, e esquecemos que a documentação é como a bússola que nos guia em meio ao caos do código. É aquele mapa detalhado que não apenas nos ajuda a lembrar o que fizemos quando voltamos para o projeto depois de um tempo, mas também permite que outros colegas de equipe se juntem e consigam contribuir sem ficarem completamente perdidos.

> Disclaimer: Se você nunca ouviu falar de Git ou GitHub, recomendo fortemente que leia o [Git4Noobs](https://github.com/DanielHe4rt/git4noobs) e pratique antes de continuar!

## O que é uma Issue?

Em inglês, _issue_ quer dizer problema, porém, utilizamos para diversas coisas além disso, como rastrear ideias, comentários, tarefas ou erros nos repositórios no GitHub.

### Criando uma issue

1. Acesso ao Repositório: Primeiro, acesse o repositório no GitHub. Certifique-se de estar logado em sua conta.

1. Navegando para Issues: No menu superior do repositório, clique na guia "Issues". Aqui podemos visualizar todas as issues do repositório (por padrão, são mostradas as issues que ainda não foram resolvidas, fechadas):

    ![Seção de issues do repositório facebook/react no GitHub como exemplo](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/yltn68a9cdvt349yl6jg.png)

1. Criando uma Nova Issue: Para criar uma nova issue, clique no botão verde "New Issue". Agora, você estará pronto para preencher os detalhes.

    ![Tela de cadastro de issue](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/9fxsjuwg1wnc35c8pjtf.png)

## A anatomia de uma issue

- **Título:** Um título conciso, porém descritivo, que resume o problema.
- **Etiquetas/Tags:** Etiquetas ou tags aplicáveis para categorizar o problema, facilitando a ordenação e o gerenciamento.
- **Labels**: As labels ajudam a categorizar e identificar o tipo de issue.
- **Assignees**: A issue pode ser atribuída a um ou mais colaboradores do projeto utilizando essa seção
- **Descrição**: Qualquer informação que possa auxiliar na compreensão ou resolução da issue (lembrando que uma issue pode ser desde um bug até uma ideia de feature nova).
    - Você pode marcar outras issues, com `#`, ou marcar pessoas com `@`

Até aqui podemos ver o poder e a quantidade de informação que podemos armazenar com as issues, mas é só isso? Não!! Há um ponto importante que temos que destacar quando estamos lidando com várias pessoas contribuindo em um projeto.

## Acompanhando uma issue

Criar a issue é apenas o primeiro passo! Acompanhar uma issue é uma parte fundamental do gerenciamento de projetos e colaboração eficaz no GitHub. Mas como se manter atualizado das discussões? Bem, temos algumas formas:
- **Ative as notificações** para acompanhar qualquer atividade relacionada a ela. Clique na opção "Subscribe" na parte superior direita da issue para receber alertas por e-mail sempre que houver novos comentários, mudanças de status ou atualizações.
- **Participe ativamente das discussões na issue**. Comente, forneça feedback e colabore com a equipe. Essas discussões podem levar a ideias melhores e a uma compreensão mais clara dos requisitos da tarefa.
- **Atribua a issue** ou **marque-o** (com `@`) a um membro da equipe responsável pelo desenvolvimento. Isso ajuda a evitar confusões sobre quem está trabalhando na tarefa e permite um acompanhamento direcionado.
- Utilize **milestones** para definir marcos ou metas específicas para a issue. À medida que o trabalho avança, atualize o status da issue e mova-a para o milestone correspondente. Isso proporciona uma visão clara do progresso geral do projeto.
- **Mantenha a descrição da issue atualizada** à medida que o desenvolvimento progride. Isso inclui adicionar informações relevantes, capturas de tela, links ou quaisquer detalhes importantes que surgirem durante o processo.


E por último mas não menos importante... Quando a tarefa estiver concluída, certifique-se de que o trabalho seja revisado e testado. Comente na issue indicando que a tarefa está pronta para revisão ou integração. Após a revisão bem-sucedida, **_feche a issue_**. Se houver ajustes futuros, é só mencionar, a issue continuará salva e poderá ser reaberta se necessário.

## Conclusão

Agora você está equipado com o poder das issues no GitHub! Elas são como post-its digitais que mantêm seu projeto na linha. Lembram o que você estava pensando (ou não) e ajudam a galera toda a trabalhar junto, mesmo quando o mundo está de cabeça para baixo.

Lembrou de uma ideia brilhante no meio da noite? Pode criar uma issue! Quer atribuir tarefas? É só marcar alguém com um 'arroba'. E não se preocupe, quando você tiver feito o seu trampo, é só revisar, testar e fechar a issue.

Então, da próxima vez que você mergulhar no código, lembre-se das suas amigas issues, elas vão fazer seu trabalho render mais e podem te poupar de futuros momentos "que diabos eu estava fazendo aqui".

> Psst, você aí! Quer agilizar ainda mais a criação de issues num projeto? Fica ligado no [GitHub Projects](https://docs.github.com/pt/issues/planning-and-tracking-with-projects/learning-about-projects/quickstart-for-projects)

## Links e referências
- [Issues | Doc do GitHub](https://docs.github.com/pt/issues)
- [Git4Noobs - Passo a passo para quem está começando agora](https://github.com/DanielHe4rt/git4noobs)
- Cover por <a href="https://unsplash.com/@mimithian?utm_source=unsplash&utm_medium=referral&utm_content=creditCopyText">Mimi Thian</a> no <a href="https://unsplash.com/photos/ZKBzlifgkgw?utm_source=unsplash&utm_medium=referral&utm_content=creditCopyText">Unsplash</a>

## 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)!