Utilizando as diretrizes para repositórios do GitHub para aprimorar a experiência do desenvolvedor

Na Nexmo, adoramos compartilhar código com nossas comunidades de desenvolvedores. Normalmente, isso significa publicar em um repositório Git no GitHub, para que qualquer desenvolvedor que queira usar o código possa fazê-lo.

Percebemos, porém, que agora que temos cerca de 300 repositórios distribuídos por algumas organizações diferentes no GitHub, pode ser complicado encontrar o que você precisa e também entender como usar cada projeto, a menos que haja boas instruções.

Para tornar a experiência do desenvolvedor ainda melhor para todos, criamos (e depois divulgamos publicamente) nossos Padrões de Repositório.

Normas adequadas para os diferentes tipos de repo

Identificamos três tipos de projetos que publicamos com frequência e adaptamos nossas diretrizes para cada um deles.

SDKs

Nossos SDKs são, sem dúvida, os repositórios mais utilizados, e temos muito orgulho deles! Usuários com diferentes níveis de experiência precisam poder acessar esses projetos e entender como podem utilizá-los em seus próprios projetos para realizar tarefas específicas da Nexmo. Dedicamos especial atenção às instruções de instalação e deixamos bem claro que a licença é muito transparente, para que nossa comunidade possa desenvolver seus projetos com base em nossos SDKs com confiança.

Aplicativos de demonstração

Publicamos diversos aplicativos de demonstração. Trata-se de aplicativos independentes destinados a demonstrar um recurso específico do Nexmo, e os disponibilizamos para que outras pessoas possam copiá-los e utilizá-los. É muito importante ter uma descrição clara dos recursos e da finalidade do projeto em um repositório como este. Também trabalhamos no licenciamento e na inclusão de configurações do Docker ou de botões do tipo “clique para implantar”, para permitir que os usuários experimentem o que criamos para eles.

O perigo de qualquer tipo de padrão é que as regras acabem saindo do controle! Muitos dos nossos repositórios são apenas uma versão pública de uma Application independente e única, criada para ilustrar um tutorial, uma postagem de blog ou um Video com o objetivo de mostrar algo específico aos desenvolvedores.

Se publicássemos apenas aqueles que estivessem perfeitamente descritos, com recursos de implantação e instruções detalhadas de uso, haveria muito menos repositórios em nossa conta do GitHub!

Na verdade, a única regra aqui é que o repositório deve ter um README que inclua um link para o que ele está apoiando.

Não me faça pensar

Criamos os Padrões de Repositório com o objetivo de estabelecer uma lista de verificação comum com os aspectos que consideramos importantes ao publicar um repositório. Cada um tinha suas próprias ideias, mas, como somos uma equipe composta principalmente por engenheiros, isso nem sempre se traduzia em excelência quando se tratava de assuntos que não envolviam código.

Ao criar listas de verificação e modelos das tarefas mais comuns, transformamos o “Faça a Coisa Certa” em “Faça a Coisa Fácil”e melhoramos a experiência dos desenvolvedores que encontram nossos projetos no GitHub.

Começamos com um modelo básico de README para dar uma estrutura simples e nos lembrar de incluir o link para a documentação do desenvolvedor e informar aos usuários como entrar em contato, caso fosse necessário. É básico, mas é MUITO melhor do que nada.

Todo repositório precisa de uma licença, e a nossa opção padrão é a MIT. Ter essas diretrizes, incluindo uma lista de verificação, nos lembra que é isso que queremos fazer.

Também temos um arquivo básico CONTRIBUTING — ele está incompleto porque é difícil generalizar, mas nos dá um ponto de partida e reduz um pouco o trabalho dos criadores de repositórios quando eles têm código para compartilhar.

A experiência do desenvolvedor está nos detalhes

Os detalhes aqui são pequenos, e há muito mais informações nas diretrizes completas — mas os detalhes realmente importam. Os desenvolvedores podem acessar seus repositórios no GitHub, talvez sem saber o que encontraram ou o que fazer a seguir. Ajudá-los a se orientar sobre onde estão, do que se trata esse repositório e para onde podem seguir são ingredientes essenciais para uma melhor experiência do desenvolvedor.