Otimizando o trabalho com seus projetos no GitHub: familiarizando-se com o Github Template Repository

Olá a todos, comunidade JavaRush! Hoje falaremos sobre código aberto e o que é necessário para criar um projeto de alta qualidade ALÉM do código que está escrito. É importante escrever um produto útil. Mas não menos importante é o design correto do repositório (repositório do projeto no GitHub). Isso ajudará na implementação de outro ponto-chave - a promoção do produto. Mesmo que o projeto seja super legal, mas se for mal desenhado, não estiver descrito pelo menos no README (você pode ler sobre o que é um README aqui ), a licença não está indicada, etc., etc., haverá sem sucesso. É que ninguém vai notá-lo. E se alguém perceber, não saberá como interagir com ele. Há muitas coisas que precisam ser preenchidas repetidamente, e não é fácil para o programador copiar e colar todas as vezes, e só para isso, neste verão, o GitHub lançou o recurso Template Repository que ajuda nisso. Por assim dizer, para automatizar o processo de criação de novos projetos. Hoje vamos entender o que é um Repositório e o que é um Repositório de Templates. Descreveremos o que deve estar no projeto além do código, em que coisas você precisa se concentrar. Vamos criar um repositório de modelos do zero e adicionar tudo o que for necessário do meu ponto de vista. E, finalmente, usaremos o Template Repository ao criar um novo repositório. Mas primeiro, vamos entender os termos. Teoria: o que deve estar no repositório geral de qualquer projeto Todo projeto de código aberto no GitHub deve ter um Perfil da Comunidade bem descrito , que contém os seguintes elementos.

1. Modelo de problema

Aqui você precisa descrever as regras para criar um problema no repositório: como devem ser chamadas, qual será o rótulo, quem será atribuído a ele. Ao criar um novo Issue, serão oferecidas as seguintes opções:

• Relatório de bug – criação de um issue para descrever um defeito no projeto;
• Solicitação de recurso – proposta de uma nova ideia para um projeto;
• Solicitação de melhoria – proposta de melhoria do projeto;
• Modelo de problema personalizado – se outras opções não funcionarem, você pode usar um modelo vazio.

Um exemplo de como isso se parece pode ser visto aqui .

2. Licença

A licença sob a qual o projeto foi escrito. É necessário para que quem vai utilizar o projeto saiba o que está garantido e o que não está. Por exemplo, a Licença Apache 2.0 diz o seguinte:

3. LEIA-ME

Esta é uma descrição do projeto, seu cartão de visita. Tudo o que precisa ser dito sobre o projeto deve estar aqui. Claro que deverá ser descrito a cada vez, levando em consideração as especificidades do projeto, mas os títulos serão os mesmos. Por exemplo:

• Visão geral – uma breve descrição do projeto;
• Utilização – como utilizar o projeto;
• Construção - como lançar um projeto, o que é necessário para isso;
• Solução de problemas - descreve quais problemas você pode encontrar e como resolvê-los;
• Notas de lançamento – descrição das alterações dependendo da versão;
• Autores - não se esqueça dos seus entes queridos;
• Contribuindo – descrição de como você pode participar do desenvolvimento do projeto;
• Código de Conduta – descrição das regras de participação;
• RELEASE_NOTES - um arquivo no qual são registradas todas as alterações para novas versões. É uma boa prática colocar isso em um documento separado e armazenar um link no README;
• CONTRIBUTING é um arquivo que descreve como você pode contribuir para o desenvolvimento deste projeto. Feito como um arquivo separado para o cabeçalho Contributing no README;
• CODE_OF_CONDUCT - arquivo que descreve as regras de participação no desenvolvimento do projeto;
• Modelo de solicitação pull - um modelo para quem irá criar uma solicitação pull.

Todas essas coisas são utilizadas projeto a projeto, independente da linguagem de programação ou de suas especificidades.

Prática: criando seu próprio modelo

Como se costuma dizer, vamos passar das palavras à ação. Agora, usando um exemplo, mostrarei como criar seu próprio modelo.

1. A primeira coisa que você precisa é de uma conta no GitHub / registre-se lá .

2. Crie um novo repositório: para fazer isso, clique em + no canto superior direito

3. Ao criar, preencha:

   • Nome do repositório - no meu caso, modelo de repositório;
   • Descrição — breve descrição do projeto;
   • Saímos de Público, embora você possa selecionar Privado;
   • Marque a caixa de inicialização README:

   • Selecione a licença sob a qual o projeto será:

     Como no meu caso o template é geral, o gitignore não é necessário: ele será adicionado para um projeto e linguagem de programação específicos.

     Portanto, clique em Criar Repositório , concluindo assim o processo de criação. O sistema nos levará automaticamente ao repositório recém-criado.

4. Preenchendo o Perfil da Comunidade : no repositório criado, acesse a aba Insights e selecione Comunidade :

   Como você pode ver, só falta preencher o modelo Código de Conduta, Contribuição, Modelo de Problema, Pull Request.

   Usando o exemplo do Código de Conduta, mostraremos como adicioná-los a um projeto.

   Clique em adicionar , o sistema solicita que você selecione Convênio do Colaborador ou Código de Conduta do Cidadão :

   Seleciono o primeiro e clico em Review and Submit .

   A seguir, você pode editar este arquivo e enviá-lo.

   Na parte inferior, selecione a opção Comprometer diretamente no branch master e clique em Enviar novo arquivo :

   Como resultado, se voltarmos ao Perfil da Comunidade , descobriremos que o Código de Conduta está marcado como adicionado:

   Os modelos de contribuição e de problema são adicionados de maneira semelhante, então não mostrarei isso. Faça Você Mesmo ;)

5. Adicionar modelo de solicitação pull .

   Mas vamos falar sobre isso separadamente.

   Não sei por que o GitHub não adicionou a mesma opção conveniente para configurar o modelo Pull-Request, então você terá que estudar a documentação e adicioná-la manualmente.

   Para fazer isso, clique em Criar novo arquivo na raiz do repositório :

   O nome do arquivo deve ser: .github/pull_request_template.md .

   Adicionamos o que precisamos ao modelo e clicamos em Enviar novo arquivo , como fizemos acima. Eu não ia reinventar a roda e encontrei um exemplo que me pareceu bastante útil.

   Desta forma todo o Perfil da Comunidade será preenchido:

6. Adicione um marcador de repositório de modelos .

   Para fazer isso, vá até a opção Configurações no repositório e marque a caixa onde diz Repositório de modelos:

   E pronto, o template para criação de novos projetos está pronto. Assim, economizaremos muito tempo no futuro quando precisarmos criar novos projetos. Isso também o ajudará a não perder detalhes importantes, pois muitas vezes você se esquece de adicionar algo, por exemplo, uma licença ou um modelo claro para um problema.

Como usar o repositório de modelos

Existem duas opções de uso:

1. Quando um modelo pertence diretamente a você: Ao criar um novo repositório, você terá a opção de criar a partir de um modelo da lista de modelos que você possui:

2. Quando o modelo é estrangeiro: também não há problemas especiais aqui. Vá para esse modelo e clique no botão Usar este modelo . Aqui usarei a animação do documento oficial:

Vamos resumir

Neste artigo vimos:

• o que é repositório GitHub;
• o que é repositório de modelos;
• o que deve estar no repositório de modelos;
• como criar um repositório de modelos;
• como usar o repositório de modelos.

Claro que com base neste template você já pode criar outros mais específicos. Por exemplo, criei mais modelos com sistemas de construção maven ou gradle já configurados. Mais ainda: você pode criar um modelo de repositório Spring Boot baseado nos dois últimos. Para agrupar todos os modelos, criei uma organização de repositório de modelos no GitHub com todos os modelos. Assine minha conta GitHub

Links Úteis

• Organização com todos os templates que criei
• Blog do GitHub: Gere novo repositório com modelos de repositório como criar um modelo para repositórios
• Ajuda do GitHub: Sobre repositórios sobre o que são repositórios.
• Ajuda do GitHub: Criando um repositório a partir de um modelo como criar um novo projeto baseado em um modelo
• Ajuda do GitHub: Licenciamento de um repositório descrição de licenciamento para projetos
• Ajuda do GitHub: Criar uma descrição de repositório para criar um repositório
• Dicas dos guias de código aberto para criar/descrever projetos de código aberto.
• Ajuda do GitHub: adicionando um modelo de solicitação pull - criando um modelo para solicitações pull.

Mais dos meus artigos

• Depurar no Intellij IDEA: um guia para iniciantes
• Guia para criar um cliente para a API Skyscanner e publicá-lo no jCenter e Maven Central [Parte 1]
• Guia para criar um cliente para a API Skyscanner e publicá-lo no jCenter e Maven Central [Parte 2]
• Criando um sistema de monitoramento de preços de passagens aéreas: um guia passo a passo [Parte 1]
• Criando um sistema de monitoramento de preços de passagens aéreas: um guia passo a passo [Parte 2]
• Criando um sistema de monitoramento de preços de passagens aéreas: um guia passo a passo [Parte 3]
• Exploração madeireira: o quê, como, onde e com quê?
• Como um teste de entrevista se transformou em uma biblioteca de código aberto
• História de sucesso. 20 horas de programação por semana, mestrado e vida pessoal
• Como encontrar um emprego? Dicas para enviar currículos