Muitos projetos de código aberto usam o Github Issues como principal meio de comunicação e ferramenta de gerenciamento de tarefas. Sua abertura e disponibilidade são um de seus maiores pontos fortes. Mas algumas dicas rápidas farão do senhor um participante muito mais responsável, especialmente em grandes projetos.
Relatórios de problemas
Do abrir uma edição para uma edição.
Do abrir duas edições para duas edições.
Do não acrescentar “Ah, a propósito, aqui está outro problema que notei” a uma questão não relacionada.
Do mantenha os fatos e as opiniões separados, de preferência os fatos primeiro e as opiniões no final. Os fatos incluem detalhes da plataforma, etapas de reprodução e o que o senhor tentou. As opiniões incluem especulações sobre as causas básicas que o senhor não investigou.
Do seja específico, especialmente nas etapas de reprodução. Em vez da instrução: “digite algum texto”, seja inequivocamente específico com a instrução: “Digite ‘Test'”. O erro pode ter a ver com a tecla shift e não será reproduzido por outros que repetidamente batem adsfasdfadsfasd. Essa não é uma ocorrência teórica – a subespecificação continua sendo um dos motivos mais comuns pelos quais os problemas válidos são fechados como não reproduzíveis.
Do reduza suas etapas de reprodução ao mínimo necessário para demonstrar seu problema. Isso facilita a ajuda de outras pessoas e, muitas vezes, a seleção revela interações relevantes.
Do especificar a plataforma ou o ambiente, geralmente o navegador e o sistema operacional. Isso é muito mais importante do que se imagina.
Do não inclua plataformas que o senhor não testou. É suficiente para ser um bug legítimo se apenas uma plataforma suportada for afetada. Os falsos positivos só serão descartados se outras pessoas não puderem reproduzir em uma plataforma que o senhor não testou, mas que foi incluída no relatório de bug.
Do tente reproduzir o problema de forma consistente em um ambiente limpo. Comece com a parte consistente.
Do Relate um problema recorrente, mesmo sem as etapas de reprodução, se o senhor não conseguir identificá-lo, após um esforço sério. Às vezes, isso pode ser feito com detalhes suficientes sobre o ambiente e o contexto, para que outros possam ajudar a preencher as lacunas.
Do use marcadores, dois pontos e até mesmo cláusulas incompletas quando apropriado. “Plataforma: Chrome/OSX, não testado em outro lugar” transmite tanta informação quanto seu equivalente gramaticalmente correto.
Do gaste mais tempo escrevendo um bom título. Ele deve ser curto, mas descritivo – semelhante à abordagem de escrever uma boa mensagem de confirmação. Os colaboradores geralmente visualizam os problemas na exibição de lista, onde somente os títulos são mostrados, e os problemas com títulos ruins serão ignorados.
Do tente resolver ou contornar o problema e forneça detalhes do que o senhor tentou, mesmo que não tenha funcionado.
Do responder às perguntas de outras pessoas se o senhor souber a resposta. Responder a perguntas não é um privilégio reservado apenas aos mantenedores. Ajudar os outros com sinceridade é a essência do código-fonte aberto!
Do não adivinhe se o senhor não souber a resposta para a pergunta de alguém. Os sinais são úteis, não o ruído, seja qual for a origem.
Do Siga o modelo de questão se for fornecido um.
Solicitação de recursos
Do Seja específico ao descrever o que o senhor deseja que seja adicionado e como isso resolveria um problema que está enfrentando.
Do não abrir um problema apenas com “make X better” ou “improve X”.
Do abrir um problema para uma solicitação de recurso com “Tornar X melhor adicionando Y porque Z”.
Do proponha uma especificação de API, mesmo que ela tenha deficiências óbvias. Isso inicia a conversa com detalhes concretos, e o progresso pode ser feito a partir daí.
Do não confunda o tamanho do recurso com a adequação ao projeto. A adequação é determinada primeiro, depois a implementação. Alguns recursos adequados levarão muito tempo para serem implementados porque são grandes. Mas nenhum recurso inadequado deve ser implementado, por mais fácil que seja.
Do não abrir solicitações hipotéticas de recursos. Se o senhor não precisa pessoalmente do recurso ou não tem o caso de uso, não está qualificado para recomendar a solução.
Do usar o recurso de reação, em vez de comentar “+1” em 2016. Um grande grupo de mantenedores de código aberto quase abandonou o trabalho com raiva por causa disso e o Github finalmente o criou. Agora, use-o!
Do feche as solicitações de recursos de que o senhor não precisa mais. Se outra pessoa tiver a mesma solicitação, ela poderá abrir um problema separado mais voltado para suas necessidades.
Solicitações de pull
Do enviar um pull request para resolver um problema.
Do enviar dois pull requests para resolver dois problemas.
Do não adicionar pequenas alterações de espaço em branco ou ponto e vírgula em commits ou Pull Requests não relacionados, mesmo que a pequena alteração esteja correta. Em vez disso, faça um commit ou Pull Request dedicado.
Do leia o contributing.md se houver uma diretriz vinculada.
Do enviar pull requests para correção de erros de digitação na documentação ou nos comentários. Essa é a maneira mais fácil e mais bem-vinda de ter seu nome adicionado à lista de colaboradores.
Do não enviar uma grande surpresa de Pull Request. Discuta primeiro a necessidade e os méritos de sua abordagem, provavelmente em um problema do Github ou no fórum de discussão do projeto ou na lista de e-mails.
Do não fique surpreso ou chateado quando o senhor ignorar o que foi dito acima e sua Pull Request for fechada.
Do não espera que todos os Pull Requests sejam mesclados.
Do não espere que outras pessoas orientem o senhor em seu Pull Request. Isso acontece quando o tempo permite, mas esperar isso é um direito equivocado. Escolha uma maneira mais fácil de contribuir se o senhor ficar preso.
Do incluir testes em sua Pull Request.
Do seguir o guia de estilo, se houver um. Se não houver, use a base de código existente como diretriz.
Do não confundir o custo de implementação com o custo de manutenção. Esse último é muito mais caro e os projetos saudáveis levam a sério as considerações de longo prazo.
Ser um ser humano decente
Do pesquise os problemas existentes para ver se o seu já foi relatado. Pode até ser que já tenha sido resolvido!
Do sinalizar outros problemas como duplicados. Às vezes, é difícil encontrar os termos de pesquisa corretos nos problemas do Github e as duplicatas são criadas apesar das melhores intenções.
Do manter os comentários curtos, concisos e no tópico. A alta densidade de informações é essencial para uma comunicação eficaz em um cenário distribuído e diversificado que é o código-fonte aberto.
Do ler a documentação. Ninguém quer ter que mostrar seu lado feio em um dia ruim. Também conhecido como RTFM™.
Do envie um e-mail para os mantenedores se o senhor trabalha em uma empresa gigante com um departamento jurídico irritante e deseja abandonar o uso do projeto sem assistência privada.
Do não envie um e-mail aos mantenedores para chamar a atenção para um problema que o senhor relatou.
Do aproveite os benefícios do software de código aberto permissivo “gratuitamente… sem restrições, incluindo, sem limitação, os direitos de usar, copiar, modificar, mesclar, publicar, distribuir, sublicenciar e/ou vender cópias do software…” garantidos pelo licença.
Do não ignore a parte em letras maiúsculas: “O SOFTWARE É FORNECIDO “COMO ESTÁ”, SEM GARANTIA DE QUALQUER TIPO, EXPRESSA OU IMPLÍCITA…” O código aberto é, em grande parte, um esforço voluntário. Qualquer ajuda adicional fornecida por colaboradores voluntários é adicional.
Do Seja caridoso com sua interpretação das palavras dos outros. Por exemplo, interpretações razoáveis de “O que o senhor não entendeu?” incluem um insulto condescendente ou uma tentativa apressada de esclarecimento. Mas a interpretação mais caridosa é que se trata de um convite aberto para ser um ponto de dados usado para melhorar a documentação. Com a diversidade global de personalidades e culturas que participam do código-fonte aberto e a baixa densidade emocional do texto escrito, sempre opte pela interpretação mais caridosa das palavras dos outros.
Quais são alguns dos seus prós e contras que eu deixei passar? Diga-me nos comentários. Siga também @jhchen para saber mais sobre código aberto e startups!
Agradecimentos a @avitaloliver, @shapiroe @timabbott por revisar os rascunhos deste post.
Sobre Jason Chen
Jason é o autor e principal mantenedor do Quill. Anteriormente, ele fundou o Stypi, um editor de código colaborativo que mais tarde foi adquirido pela Salesforce. Ele é fascinado pela disseminação e retenção de conhecimento e ideias.