Documentando o desenvolvimento com issues

Conteúdos

1. Introdução
2. O que é uma Issue
3. A anatomia de uma issue
4. Acompanhando uma issue
5. Conclusão
6. 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 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.

2. 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):

   

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

   

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

Links e referências

• Issues | Doc do GitHub
• Git4Noobs - Passo a passo para quem está começando agora
• Cover por Mimi Thian no Unsplash

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!