15 dicas para melhorar seu fluxo no Github

Eu trabalho no desenvolvimento de software há 10 anos e ao longo do caminho, tive a oportunidade de colaborar em vários projetos de código aberto e também trabalhei em muitos projetos de código aberto onde usamos o Github como nosso repositório de controle de versão, em equipes pequenas e grandes.

Em minha jornada, segui diferentes fluxos de trabalho dependendo do projeto e hoje quero compartilhar com você o que considero ser um fluxo de trabalho eficaz e pragmático para a criação e manutenção de software de boa qualidade que possa ser aplicado a qualquer projeto.

Os atributos do software de boa qualidade são muitos: robustez, testabilidade, resiliência, modularidade, facilidade de manutenção, usabilidade, segurança, desempenho, escalabilidade e muito mais, dependendo do tipo de aplicativo que você está construindo. Neste artigo, vou focar principalmente nas seguintes características:

  • Boa documentação: leia-me, sites de documentação e changelogs.
  • Padrões de codificação bem definidos e convenções.
  • Versão adequada com semver.
  • Testes automatizados: não são muitos, foquem-se em testes funcionais de não regressão.
  • Felicidade do desenvolvedor, claro!

Para conseguir isso, estou propondo um fluxo pragmático do Github, alavancando ferramentas de código aberto que ajudam a facilitar e automatizar muitas das tarefas necessárias para atingir esse objetivo.

Se você está trabalhando em um projeto de código aberto que deseja publicar seu projeto Github, isso é um fato. O Git e o Github mudaram radicalmente a forma como o OSS é desenvolvido, tornando-se a linguagem comum de fato para controle de versão e local definitivo para colaboração, respectivamente.

O fluxo de trabalho oficial proposto pelo Github é chamado fluxo do github e está muito bem documentado em seus guias do site.github.com/introduction/flow , a maioria dos projetos de código aberto segue esse fluxo de trabalho com sabores ligeiramente diferentes.

O fluxo de trabalho do Github é muito flexível no sentido de não informar como liberar e documentar mudanças, qual estratégia de mesclagem usar ao aceitar solicitação pull, quais ferramentas usar, quais padrões de compromisso seguir ou o que revisar antes de aceitar um puxar pedido, isso é você e isso faz muito sentido, já que não há solução universal para as necessidades de cada equipe.

A seguir, uma lista de recomendações com base na minha experiência:

Eu trabalho principalmente (quase exclusivamente) em JavaScript, muitas das ferramentas que mencionarei fazem parte do ecossistema JS, no entanto, os princípios se aplicam a qualquer idioma.

Priorize seus problemas e acompanhe seu progresso com os projetos do Github

Em setembro de 2016, o recurso Projetos foi lançado. É uma ferramenta que permite criar quadros de estilo kanban para organizar, priorizar e rastrear seu trabalho no nível de repositório e organização. Se você usar os problemas do Github, sugiro que use o recurso para organizar e comunicar melhor as prioridades do projeto e os esforços atuais. Você pode aprender mais sobre o seguinte link help.github.com/articles/tracking-the-progress-of-your-work-with-project-boards

Classifique seus problemas com tags

O Github fornece ótimas funcionalidades de filtragem. Se você estiver trabalhando em um projeto de código aberto, você quer que as pessoas colaborem em seu projeto, além de proporcionar uma boa experiência aos desenvolvedores que o usam. Ao codificar seus problemas, os desenvolvedores poderão navegar com mais facilidade na lista de problemas, economizando tempo e permitindo que contribuam com menos atrito de entrada.

Aproveite os modelos do Github para solicitações e problemas de extração

Tomando o tempo para escrever modelos do Github para seus problemas e puxar a solicitação certamente irá pagar; Isso forçará ou, pelo menos, ajudará os desenvolvedores a relatar erros e solicitar recursos da maneira padrão, com todas as informações necessárias para resolvê-los.

Saiba mais em blog.github.com/2016–02–17-issue-and-pull-request-templates

Algumas diretrizes gerais para relatórios de erros :

Antes de enviar um problema, verifique se você concluiu as seguintes etapas:

  • Verifique se você está na versão mais recente
  • Usou o recurso de pesquisa para garantir que o bug não tenha sido informado antes

Os relatórios de erros devem conter as seguintes informações:

  • Resumo: uma breve descrição.
  • Etapas para se reproduzir: como você encontrou o bug? Instruções para reproduzi-lo.
  • Comportamento esperado: como você esperava que ele se comportasse?
  • Comportamento real: como isso realmente se comportou?
  • Referências: Links para quaisquer tickets relacionados ou fontes de informação.
  • Se possível, anexe a documentação visual do bug. Capturas de tela, vídeos e / ou gifs animados.

Puxe as diretrizes gerais da solicitação :

  • Certifique-se de que não existem pedidos de extração que tentem resolver o problema mencionado.
  • Verifique se há problemas relacionados no rastreador de problemas.
  • Alterações não triviais devem ser discutidas primeiro sobre um problema.
  • Deixe-nos saber que você está trabalhando no problema.
  • Desenvolver em um ramo de tópico, não mestre.
  • Forneça uma descrição de solicitação de extração útil.
  • Siga as diretrizes de comprometimento do projeto.
  • Escreva uma boa descrição do seu PR.
  • Link para o problema do Github na descrição.

Use a linha de comando

O console é seu amigo. Na minha experiência, aprender a interagir com o Github na linha de comando é o melhor uso do seu tempo, se você trabalha com tecnologias de código aberto. Existem muitas interfaces gráficas agradáveis, no entanto, nenhuma delas dará a flexibilidade da linha de comando. Há também ferramentas que tornarão a vida muito mais simples e um desenvolvedor mais eficiente que esteja disponível apenas para a linha de comando:

  • hub é um wrapper de linha de comando para o git que o torna melhor no GitHub. Seja você um iniciante ou um colaborador experiente em código-fonte aberto, o hub facilita a busca de repositórios, a navegação em páginas de projetos, o fork repos e até o envio de solicitações de pull, tudo a partir da linha de comando. hub.github.com
  • tj / git-extras é um conjunto de utilitários git como resumo de repo, repl, população de changelog, porcentagens de autor commit e mais. github.com/tj/git-extras

Siga os Padrões de Mensagem de Confirmação Estrita e os Compromissos Definidos

Sempre defina e siga padrões de mensagem de compromisso claros para seus projetos, algumas diretrizes gerais são:

  • Confirme cada correção como uma mudança separada.
  • Forneça mensagens de confirmação úteis.
  • Forneça uma mensagem de confirmação curta na primeira linha (50 a 100 caracteres). gitk a saída de gitk ou git log --oneline pode ajudar você a entender o motivo.
  • Faça referência ao problema do git no corpo da sua mensagem de commit.

Além disso, sugiro fortemente que você esclareça suas mensagens para uma melhor geração de changelog. Quando você alcança suas mensagens, seus changelogs podem ser mais informativos. As convenções e a geração de changelog do AngularJS são um ótimo exemplo gist.github.com/stephenparish/9941e89d80e2bc58a153#generating-changelogmd

Definir padrões de estilo de codificação e configurar ganchos de pré-consolidação

Definir padrões de codificação e aplicá-los através de ganchos de pré-commits é essencial para escrever código sustentável. Ao seguir esses padrões, você garante que todos os códigos tenham a mesma aparência, independentemente de quem os escreveu, facilitando o controle e a manutenção do código escrito por outra pessoa.

Minha configuração recomendada é Prettier e StandardJS, no entanto, isso é uma questão de preferência, há muitos outros e você também pode configurar um personalizado, contanto que você siga um padrão de codificação que você irá se beneficiar.

typicode / husky é uma ótima ferramenta para configurar ganchos de pré-consolidação.

Configurar testes automatizados e verificações em solicitações de extração

Testes funcionais automatizados, segurança e verificações de estilo de código contra cada solicitação de recepção são altamente desejáveis, você não quer fazer isso manualmente. Um servidor de integração contínua, como o TravisCI, pode ser configurado rapidamente para executar esses testes automaticamente na ramificação do tópico toda vez que uma solicitação pull é enviada e o Github pode ser configurado para impedir que o desenvolvedor mescle solicitações pull que não passam no teste. Se esses testes automatizados falharem, o Github exibirá uma mensagem na solicitação pull do solicitante para corrigi-los.

Saiba mais em docs.travis-ci.com/user/pull-requests

Proteja seu ramo principal e exija revisões de código

O Github oferece a possibilidade de proteger o seu branch master contra commits diretos, push forçado e rebase. Isso é muito importante ao colaborar com outras pessoas em um projeto. Além disso, você deseja revisões de código conforme a etapa necessária para mesclar o código no mestre. Ao configurar isso na guia de configurações de cada repositório.

Protegendo o mestre e impondo as revisões de código, você ficará tranqüilo em saber que será improvável que códigos indesejados cheguem ao mestre e que ninguém na equipe afetará os outros, modificando o histórico do git mestre ou empurrando o código não revisado.

Squash seus pedidos de pull

Este é um debate quente: Merge vs Squash vs rebase. Eu acredito que a mesclagem de squash é a melhor abordagem pelas seguintes razões:

  • nem todos os desenvolvedores sabem como rebase corretamente uma solicitação pull em cima do master, isso é um fato. Muitos desenvolvedores simplesmente mesclam o mestre em cima de suas alterações. A mesclagem de squash se livra dessas mensagens de mesclagem que são inúteis para construir um changelog mais tarde e adicionar ruído ao log do git.
  • nem todos os contribuidores seguirão as diretrizes de confirmação, a mesclagem de squash permite controlar a mensagem de confirmação que está no branch master.

Para seguir com sucesso um fluxo de trabalho de mesclagem de squash, é necessário que cada solicitação de recepção tenha um escopo para um recurso específico, correção de bug ou tarefa.

Semver, Tags Github, Lançamentos e Changelogs Automatizados

O controle de versão é super importante no software e especialmente em projetos de código aberto, onde muitos projetos dependem do seu software. Versões semânticas tornarão a vida mais fácil para todos, pois saberão exatamente quando quebrar as alterações adicionadas ou se uma nova versão contiver um novo recurso ou uma correção de bug, apenas procurando os números de versão.

Dado um número de versão MAJOR.MINOR.PATCH, incremente o:

  • Versão MAJOR quando você faz alterações de API incompatíveis
  • Versão MINOR quando você adiciona funcionalidade de uma maneira compatível com versões anteriores, e
  • PATCH versão quando você faz correções de bugs compatíveis com versões anteriores.

Rótulos adicionais para pré-lançamento e metadados de construção estão disponíveis como extensões para o formato MAJOR.MINOR.PATCH.

Além de alterar sua versão do package.json, gerar uma tag git para cada versão é uma boa prática.

Saiba mais em semver.org .

A especificação de Commits Convencionais propõe a introdução de uma convenção leve padronizada sobre as mensagens de confirmação. Essa convenção se encaixa com a SemVer, solicitando aos desenvolvedores de software que descrevam em mensagens de confirmação, recursos, correções e quebra de alterações que eles fazem.

Ao introduzir essa convenção, criamos uma linguagem comum que facilita a depuração de problemas entre os limites do projeto.

convencionalcommits.org .

TravisCI pode ajudar a automatizar este processo docs.travis-ci.com/user/deployment/releases

Você também pode encontrar esses pacotes úteis dominique-mueller / automatic-release , semântica-release / semântica-release .

Automatize Implantações com Ganchos de Tag

Não é necessário usar ramificações de release como o Git Flow proposto. Você pega o artefato de implantação de suas tags do git; No link, você aprenderá mais sobre como implantar tags git no heroku usando TravisCI docs.travis-ci.com/user/deployment/heroku . É muito simples, você só precisa definir o atributo tags para true. Você pode realizar o mesmo comportamento com qualquer outro servidor de CI.

Para um ambiente de desenvolvimento você pode configurar o hook que implanta o master commit mais recente e para ambientes de recursos, não há ramos tão longos, opcionalmente você poderia provisionar ambientes de teste efêmeros para cada requisição de PR, no entanto, isso é mais complexo e não é realmente requeridos.

Configurar um canal de streaming do Github na sua sala de chat

Esta é uma maneira muito conveniente de rastrear a atividade em seus repositórios do Github em um único lugar, o lugar onde você se comunica com sua equipe é o ideal. Estas são simples notificações transmitidas em uma sala de tópicos ou várias. Mas há muito mais que você poderia fazer nas suas salas de bate-papo, em 2013 o Github cunhou o termo ChatOps , você pode aprender sobre isso aqui youtube.com/watch?v=NST3u-GjjFw

Automatizar atualizações de dependência

Manter suas dependências atualizadas é tarefa demorada e repetitiva, ideal para automação. Felizmente, existem muitas ferramentas que ajudarão você a manter suas dependências atualizadas criando automaticamente solicitações de pull em seu projeto com as versões mais recentes, seus testes automatizados de não regressão serão executados contra essa solicitação pull e, se ela passar, provavelmente seu código continuará funcionando normalmente uma vez que você mescla. Tenha cuidado com grandes mudanças de versão, verifique sempre.

A ferramentas casal que ajudarão você é greenkeeper.io e david-dm.org

Melhore sua experiência de interface do usuário do Github com extensões

Você pode ver mais sobre o GitHub Browser Extensions .

O Kikobeats / awesome-Github tem mais ferramentas que você usa para melhorar seu fluxo no github.

Aprendizado e Melhoria Contínua

As práticas de desenvolvimento de software do Github e do software livre estão em constante e rápida evolução, mantendo-se atualizado com as práticas e ferramentas mais recentes seguindo os anúncios do Github e seguindo os padrões e práticas da comunidade. O canal GitHub Training & Guides no youtube é um ótimo recurso. youtube.com/githubguides