O que é o GitHub Discussions? Um guia completo

O que está incluído

Introdução do GitHub Discussions: Como habilitar o GitHub Discussions em seu repositório e casos de uso populares.
Melhores práticas para usar o GitHub Discussions: Principais dicas para utilizar o GitHub Discussions com sucesso como uma ferramenta de engajamento comunitário.
GitHub Discussions vs. GitHub Issues: Quando usar cada recurso: Quando e como usar Discussions e Issues em um projeto e como transformar Discussions em Issues (e vice-versa).

Criar um ótimo software envolve mais do que apenas o código-fonte. Se você possui uma comunidade em crescimento, há muitos outros aspectos que podem ocupar seu tempo. Há questões como planejamento de roadmap, colaboração com sua comunidade em relação a possíveis recursos, compartilhamento sucinto de atualizações de progresso com colaboradores, atração e integração de novos contribuidores, entre outras.

Tudo isso pode ser resolvido com um espaço central de encontro onde mantenedores e contribuidores podem se reunir para capturar ideias, conversar e planejar o futuro.

A resposta? GitHub Discussions. Lançado em 2020, o Discussions traz fóruns comunitários para o GitHub, ajudando comunidades de código aberto, equipes de desenvolvedores e empresas a fazerem perguntas, compartilharem ideias e construírem conexões entre si com mais facilidade, e isso no mesmo ambiente do seu código.

Neste guia, exploraremos o GitHub Discussions, abordando formas de usá-lo, melhores práticas e como ele complementa outros recursos do GitHub (como o Issues) para validar a experiência completa do desenvolvedor.

Introdução ao GitHub Discussions: Elementos básicos

Concebido para qualquer comunidade de desenvolvedores que trabalha em conjunto rumo ao mesmo objetivo, o GitHub Discussions oferece um grande benefício: o funcionamento diretamente integrado ao seu repositório (ou seja, exatamente onde você já está trabalhando e onde sua comunidade se encontra), reduzindo a necessidade de alternância de contexto ao gerenciar fóruns de terceiros em outros sites.

Ou seja, os desenvolvedores e colaboradores podem acessar as discussões sem sair do ambiente familiar do repositório, tornando a colaboração mais eficiente e conveniente.

Como habilitar o GitHub Discussions em seu repositório

O Discussions pode ser habilitado em qualquer repositório público ou privado por um administrador, mantenedor ou qualquer pessoa com permissão de escrita. Explicamos como:

Abra as configurações do seu repositório e vá para “Recursos”.
Marque a caixa ao lado de “Discussions”.
Crie uma postagem de boas-vindas para iniciar o seu fórum

É simples assim. Não acredita em nós? Aqui está a prova 👇.

Um GIF que mostra um usuário do GitHub habilitando o Discussions em seu repositório.

Saiba mais sobre a introdução ao Discussions

O que o GitHub Discussions é capaz de fazer: Exemplos de casos de uso comuns

O Discussions oferece a capacidade de se envolver diretamente com suas comunidades e colaboradores, tudo enquanto permanece no GitHub. Para facilitar, também fornece recursos como rotulagem, marcação de respostas úteis, votação e muito mais.

Aqui estão alguns meios que comunidades de código aberto e equipes encontraram para usar o GitHub Discussions:

Criar anúncios para a comunidade: Seja você um administrador, mantenedor ou contribuidor, é possível utilizar o Discussions na criação de anúncios para a comunidade sobre próximos lançamentos, decisões de roadmap e muito mais. Precisa de provas? Veja como a comunidade de código aberto Node anunciou seu roadmap para sua comunidade.
Compartilhar ideias e obter feedback da comunidade: Talvez você precise de feedback sobre um problema que está tentando resolver. Ou talvez você queira compartilhar ideias sobre novos recursos que considera para integrar um futuro sprint. O Discussions é projetado para tornar o envolvimento da comunidade simples e colaborativo, e um caso de uso popular entre comunidades de código aberto e equipes é aproveitá-lo para compartilhar ideias e obter feedback (veja como a comunidade de código aberto Gatsby fez exatamente isso).
Discutir um novo lançamento: Algumas comunidades de código aberto utilizam Discussions para responder a perguntas de suas comunidades mais amplas sobre um novo lançamento. Isso é algo que vimos com grande efeito na equipe do React, que se beneficiou do Discussions para tirar as dúvidas sobre seu último lançamento (e também explicar um pouco mais sobre as particularidades da novidade).
Fixar conversas importantes para destacá-las: O Discussions tem a funcionalidade de fixar conversas e anúncios no topo do feed, o que facilita garantir que sua comunidade ou equipe tenha acesso a informações importantes. Um ótimo exemplo deste recurso em ação vem da comunidade Next.JS, que fixa conversas importantes e úteis no topo de seu quadro do Discussions.
Determine tópicos que estão em alta na sua comunidade: Você pode classificar todas as conversas em uma determinada instância do Discussions com base na quantidade de votos que receberam, e isso pode ser feito por dia, mês, ano ou o tempo todo. Esta é uma excelente maneira de acompanhar quais conversas estão despertando mais interesse em sua comunidade.
Fazer perguntas e obter respostas com postagens de Q&A: Tem uma pergunta sobre uma pull request, questão ou problema que está enfrentando? Publique-a em uma discussão de Q&A para encontrar uma resposta. E a melhor parte: você pode marcar quais respostas são úteis para que outras pessoas possam rapidamente descobrir o que mais ajudou você. Quer um exemplo? Experimente dar uma olhada no quadro de Discussion da comunidade jsPsych, que apresenta várias postagens de Q&A (com respostas úteis marcadas).
Coordenar recursos de engenharia: Outro caso de uso popular para o Discussions entre algumas comunidades é a coordenação de recursos da equipe e o planejamento de sprints. Além disso, é possível criar e atribuir Issues diretamente a partir de suas discussões, o que facilita o planejamento de sprints (falaremos mais sobre isso em breve).
Discutir questões gerais: Você pode usar o Discussions para conversar (sobre a vida profissional ou pessoal) com postagens gerais que engajem sua comunidade ou equipe. Por exemplo, a comunidade Next.JS utiliza o Discussions para mostrar quais empresas e sites estão usando seu software.

Práticas recomendadas para usar e moderar o GitHub Discussions

O Discussions oferece um fórum comunitário diretamente em seu repositório, facilitando a comunicação com colaboradores e o incentivo à comunidade, tudo diretamente do GitHub.

Ainda assim, todos sabemos que fóruns bem-sucedidos precisam de moderação para manter a produtividade e utilidade das conversas. Independentemente de usar o Discussions para uma pequena equipe ou como parte de um grande projeto de código aberto, destacamos algumas práticas recomendadas:

Use etiquetas para manter seus espaços organizados. O Discussions oferece a opção de etiquetas, que podem ser personalizadas para atender às suas necessidades. Elas podem ser aplicadas a qualquer discussão e utilizadas para destacar informações importantes, facilitar a busca por uma discussão específica e evitar conteúdo duplicado.
Nas discussões de Q&A, marque a resposta que responde à pergunta. Um caso de uso popular do Discussions é a criação de postagens de Q&A, que podem ser úteis para conferir as respostas da sua equipe ou comunidade. Porém, ao fazer uma pergunta, não se esqueça de marcar a resposta que respondeu à pergunta. Esta é uma maneira de ajudar a evitar conteúdo duplicado (ou postagens antigas). Também é adequado atribuir votos positivos a qualquer comentário ou resposta que seja útil ou assertivo.

Uma imagem exibindo uma resposta marcada como útil em uma conversa no GitHub Discussions.

Use o Discussions para acionar automações: O Discussions é compatível com a API GraphQL, o que significa que é possível utilizar o GitHub Actions para acionar automações com base em novos eventos de discussões e comentários. Casos de uso populares incluem acionar notificações de aplicações de bate-papo quando uma nova discussão ou comentário é criado, e enviar atualizações automáticas para sites com discussões importantes, como anúncios.
Transforme colaboradores em moderadores e atribua permissões de triagem. Se a sua comunidade é grande o suficiente, é viável transformar vários colaboradores em moderadores para ajudar a manter o funcionamento adequado da sua instância do Discussions. Para isso, basta atribuir permissões de triagem às pessoas no seu projeto, transformando-os em moderadores com a capacidade de marcar respostas, gerenciar o fórum, remover conteúdo e muito mais.
Utilize o recurso de classificação superior para encontrar conversas em alta. Quando um fórum do Discussions cresce consideravelmente, provavelmente passará a ter uma intensa atividade diária e muitas postagens. Se você não tem tempo para analisar todas as conversas, pode verificar as que estão em alta ao selecionar o recurso de classificação superior e configurando a visualização conforme o período desejado (dia, semana, mês, ano ou todos).

Uma imagem exibindo uma resposta marcada como útil em uma conversa no GitHub Discussions.

GitHub Discussions vs. GitHub Issues: Quando usar cada um deles

Uma dúvida comum entre os desenvolvedores que são novos no GitHub Discussions é quando exatamente usar o Discussions e quando usar o Issues.

A resposta curta: O recurso Discussions é ótimo para promover perguntas e ideias que requerem comunicação da equipe antes de tomar uma decisão, enquanto as Issues reúnem as etapas que foram definidas para o trabalho em pauta.

A resposta um pouco mais longa: Em qualquer projeto ou sprint, há aspectos que você precisa discutir e coisas que precisa fazer. As Discussions servem para, por mais que pareça óbvio, discutir assuntos. Já as Issues servem para catalogar o trabalho que precisa ser feito depois que a decisão sobre como avançar for tomada.

Quando usar o GitHub Discussions

O GitHub Discussions é mais adequado como uma ferramenta para compartilhar perguntas, ideias, conversas, solicitações de comentários (RFC), planejamento de recursos e anúncios.

Quando usar o GitHub Issues

As Issues servem para rastrear e catalogar partes de um trabalho específico que precisa ser feito depois que uma decisão sobre como avançar for tomada. Essas partes abrangem bugs a serem corrigidos, recursos a serem desenvolvidos e outras tarefas concretas que fazem parte do progresso do projeto.
As Issues costumam ser usadas depois que as Discussions promoveram a tomada de decisão e a definição sobre o que precisa ser feito. Quando esses recursos são usados juntos, é possível alcançar mais eficiência ao reservar Issues e pull requests para trabalhos ativos e Discussions para conversas, perguntas e engajamento com a comunidade.

E há mais um benefício: você pode fazer referência a uma Discussion em uma Issue, o que pode ajudar a trazer contexto e informações de base para um trabalho. Também é possível converter uma Issue em uma Discussion se precisar de informações e decisões adicionais antes da conclusão de uma tarefa.

Como criar uma Issue a partir de uma Discussion

O recurso Discussions oferece uma plataforma de comunicação assíncrona que armazena informações históricas, notas, ideias e muito mais. A melhor parte: você pode criar uma Issue a partir de uma Discussion, ou seja: é possível anexar suas notas e decisões que geraram um trabalho diretamente em uma Issue.

Para isso, vá para a barra lateral direita e clique em Criar Issue a partir de uma Discussion e, em seguida, crie sua Issue e atribua-a a alguém (ou a si mesmo).

Como converter uma Issue em uma Discussion

Sejamos honestos: às vezes, as pessoas utilizam o recurso Issues como um depósito padrão para qualquer tipo de conversa ou assunto que não tenha uma tarefa executável envolvida. Em outras situações, as pessoas criam uma Issue e só depois percebem que precisam de uma decisão da equipe antes de começarem a avançar.

Em casos como este, você pode converter uma Issue em uma Discussion, bastando acessar o canto direito da Issue e selecionar “Converter em Discussion”.

Essa ação fecha e bloqueia a Issue, preservando o título, a descrição e o autor para a nova Discussion.

Informações importantes

Quer você esteja planejando um roadmap de recursos, fazendo perguntas sobre algo no qual está trabalhando ou engajando uma comunidade de código aberto que está desenvolvendo um software que você usa, o GitHub Discussions oferece um espaço central para todas as comunidades, tanto de código aberto quanto privadas, se conectarem e colaborarem.

O Discussions foi concebido com três objetivos em mente:

Proporcionar um espaço comunitário centralizado para conversas e perguntas (e facilitar a vida dos mantenedores quando se trata de Issues e pull requests).
Criar um lugar para que recém-chegados e colaboradores não relacionados a códigos participem de uma comunidade maior.
Destacar os contribuidores do projeto para promover o desenvolvimento da próxima geração de mantenedores.

Experimente ativá-lo hoje mesmo em seus repositórios públicos ou privados ou participar de comunidades de código aberto que sejam do seu interesse.