Guia de boas práticas de desenvolvimento

Bouckaert edited this page May 31, 2017 · 3 revisions

Este documento tem por objetivo registrar as boas práticas de desenvolvimento adotadas pela comunidade Openredu, tornando acessível aos colaboradores interessados em contribuir com o código das aplicações, os requisitos mínimos necessários para que mudanças sejam introduzidas ao código, bem como o fluxo de atividades recomendadas para a evolução do mesmo, seja na resolução de problemas ou criação de funcionalidades.

Acreditamos no ganho social promovido pelo software livre e exaltamos todas as contribuições recebidas, pensando nisso e por se tratar de uma comunidade, incentivamos que quaisquer sugestões de alteração no código sejam previamente discutidas com a comunidade através do fórum, a fim de alinhar as mudanças propostas com a visão da comunidade, evitando que sua contribuição fique no limbo e não seja incorporada ao código.

Repositório e controle de versão

Nós utilizamos o git como sistema de controle de versão e ainda que não sejam necessários poucos comandos para compartilhar sua contribuição, recomendamos uma boa compreensão dos fundamentos do git, pois comandos como stage, rebase, diff e log podem ser úteis.

O repositório oficial do core da aplicação web Openredu se encontra publicamente disponível no github, para fazer o checkout e enviar as alterações para o repositório oficial, você precisa de uma conta no Github. Para realizar as configurações necessárias, basta seguir as instruções de setup.

Setup do ambiente de desenvolvimento

Ao realizar alterações no código, você precisará realizar testes e validar as mudanças em ambiente de desenvolvimento, para isso será necessário realizar o setup do Openredu na sua máquina de desenvolvimento. A comunidade tem se esforçado em documentar diversas alternativas de realização do setup:

  • Setup local (Ubuntu)

https://github.com/Openredu/Openredu/wiki/OpenRedu-Setup-(Ubuntu)

  • Virtualização com Vagrant

https://github.com/Openredu/Openredu/wiki/Openredu-Vagrant

  • Demais alternativas

Mac OS script
maquina virtual
vultr cloud

Termo de compromisso de contribuidor(CLA)

Todos os contribuintes do Openredu devem assinar o CLA para que a comunidade tenha o direito legal de usar o seu código. Se você é um empregado de uma empresa, você deve garantir que a empresa permite contribuições para projetos Open Source.

Reportando um problema

A gestão dos bugs é feita pelo github e uma issue pode ser aberta por qualquer usuário. As issues do github são a maneira adequada de compartilhar e discutir as tarefas, aprimoramentos e bugs com o resto da equipe. Entretanto, recomendamos que algumas informações sejam registradas para que o bug seja prontamente rastreado e validado.

  • Título: é uma pequena sentença que de forma sucinta descreve o que é o bug;
  • Descrição: que é uma descrição completa do bug;
  • Etapas: Etapas necessárias para reproduzir o comportamento que gerou o bug;
  • Resultado: Comportamento equivocado da aplicação, que ocasionou no bug;
  • Resultado esperado: Comportamento esperado da aplicação, caso o bug não houvesse ocorrido;
  • Versão: que se refere à versão da aplicação na qual o bug foi encontrado;
  • Browser: navegador e versão do mesmo, usado para acessar a plataforma;
  • OS: que se refere ao sistema operacional em que se manifestou o problema,
  • Anexo: na qual podemos adicionar documentos, imagens capturadas, ou qualquer outra informação que ajude na identificação e resolução do bug.

Uma vez cadastrada a issue, um membro da equipe deve confirmar a pertinência da solicitação e atribuir a devida label:

  • Backport - Para problemas em versões antigas cuja solução já foi implementada em versões posteriores;
  • Bug - Para problemas confirmados com funcionalidades existentes;
  • Crítico - Causa perda ou corrupção de dados, congela a aplicação após uma operação específica ou permite que usuários não autenticados vejam conteúdo protegido;
  • Deploy - Referente ao processo de instalação/configuração;
  • Design - Solicitações referente a interface gráfica e componentes do front-end
  • Discussão - Solicitações carentes especificação, cujo o plano de ação precisa ser discutido com os membros da equipe.
  • Melhoria - Solicitações de melhoria em funcionalidades já existentes;
  • Nova funcionalidade - Solicitações de novas funcionalidades;
  • Revisão - Solicitação de revisão de código;
  • Wishlist - Solicitações aceitas pela equipe, aptas para desenvolvimento.
  • Prioridade Baixa - Solicitações aceitas pela equipe, mas sem urgência de resolução.
  • Prioridade Media - Solicitações aceitas pela equipe, aptas para desenvolvimento.
  • Prioridade Alta - Solicitações aceitas pela equipe, cuja resolução é imprescindível.

Versionamento

O versionamento do Openredu é uma adaptação do semantic versioning e também consiste em três números inteiros, positivos e sequenciais separados por pontos (e.x., 2.3.23).

  • Major (primeiro número) será incrementado anualmente a partir do planejamento de prioridades (roadmap) da comunidade. Assim que todas as funcionalidades forem incorporadas ao código teremos uma major release. A compatibilidade com versões anteriores não é garantida. Sempre que a major é incrementada, o patch e minor devem ser redefinidos para 0.

  • Minor (segundo numero) deve ser incrementado quando introduzir , remover ou adicionar uma funcionalidade ao Openredu. Estas alterações devem ser compatíveis com versões anteriores da mesma linha major (mas não necessariamente com versões subsequentes). Sempre que a minor é incrementada, o patch deve ser redefinido para 0.

  • Patch (terceiro numero) deve ser incrementado quando correções de bugs ou melhorias na segurança forem introduzidos. Estas alterações devem ser totalmente compatíveis com versões anteriores da mesma linha minor.

  • Sufixo pode ser adicionadas ao versionamento acrescentando um hífen e um identificador para especificar a qualidade esperada de uma versão, nesses casos algumas regras do versionamento podem ser flexibilizadas. São eles:

    • rc (releases candidate) este sufixo deve aparecer próximo ao lançamento de uma release, adicionado em versões extensivamente testadas e supostamente livre de bugs. (e.x., 1.2.3-rc )
    • beta este sufixo é usado para funcionalidades completas que serão disponibilizadas para realização de testes pela comunidade. Feedback pode ser dado através do fórum. (e.x., 1.2.3-beta)

Padrão de Commit

Os commits devem ser atômicos, se duas correções distintas são realizadas, elas devem ser implementadas em dois commits diferentes. As mensagens de correção de issue devem descrever o que mudou e fazer referência ao número da issue associada à mudança.

< Título >

  • Deve conter a descrição sucinta da alteração:
  • No maximo 50 caracteres;
  • Use o imperativo: "Corrige" e não "corrigiu", "corrigindo" ou “correção”;
  • Inicie a frase com letra maiúscula;
  • Sem ponto (.) No final.

< linha em branco >

< Corpo >

  • Deve conter a descrição detalhada da alteração:
  • Configure seu editor(nano¹, Vim²) para quebrar a linha em 72 caracteres

< linha em branco >

< Resolve #XXX >

  • Usado para fechar automaticamente a issue (numero XXX) relacionada a modificação.

< linha em branco >

< Obs >

  • Usado para fazer referência a outras issues, débito técnico e demais links relevantes.

Para uma melhor compreensão da importância de um commit descritivo e alguns exemplos leia chris beams e tbaggery.

Política de ramificação (branch policy)

Na comunidade, utilizamos uma política de ramificação própria que busca unir a flexibilidade do fork workflow, bastante comum a projetos de código aberto, com as boas práticas de gestão e lançamento do gitflow workflow.

Master

Assumimos a convenção de que o branch master é o default para desenvolvimento, equivalente ao develop do gitflow, sendo assim durante o ciclo de desenvolvimento de novas releases toda alteração deve partir(checkout) e retornar(merge) deste branch. Tornando este um branch atualizado porém instável, inapropriado para deploy em produção.

Feature

Toda funcionalidade deve ser implementada em um branch próprio, ramificado a partir do master e integrado de volta quando concluída a funcionalidade. Uma vez que o pull request for aceito o branch será apagado.

Hotfix

Correções que precisam ser aplicadas com urgência também devem ser criadas em um branch próprio a partir do master, entretanto será possível incorporar as modificações em quaisquer branches que forem necessários.

Release

Ao final do ciclo de desenvolvimento, quando os milestone definidos pelo roadmap da comunidade forem devidamente homologados, uma release é lançada a partir da ramificação do branch master para um novo branch de release. A deste momento em diante, apenas patches(backports) serão incorporados. O que torna esse branch estável para deploy em produção.

Fluxo de desenvolvimento

O fluxo abaixo representa o ciclo de vida de evolução do código e as etapas necessárias para que mudanças sejam incorporadas, sejam elas correções de bugs ou novas funcionalidades.

Solicitação de mudança -> wishlist -> Estimar impacto / recursos -> [Sugestão aceita?] roadmap -> implementar <-> CI <-> Codereview -> Deploy em homologação -> Q&A -> Deploy em produção (solicitação finalizada)

Solicitação de mudança

Discuta a mudança com a comunidade. Os membros da equipe podem ter conselhos sobre a melhor maneira de abordar o problema. Depois de entrar em acordo sobre um plano geral de implementação, peça ao membro da equipe que lhe atribua a issue. Esta discussão pode acontecer no fórum ou na issue.

Wishlist

Uma vez que solicitação de mudança esteja alinhada com as diretrizes da comunidade, uma issue será aberta com a tag Wishlist. Esse “baú de ideias” já validadas pela comunidade é um bom ponto de partida para desenvolvedores interessados em contribuir com o código. Caso você queira se voluntariar para codificar essa issue, solicite a um membro da equipe que atribua a issue a você.

Estimar impacto / recursos

O core de desenvolvedores da comunidade realiza a gestão de suas atividades utilizando ferramentas como scrum e Jira. Frequentemente, nas reuniões de planejamento da sprint são realizadas estimativas de impacto e recursos necessários para implementação das solicitações de mudança presentes na wishlist.

Roadmap

Uma vez que os recursos necessários à implementação da mudança estão adequados ao cronograma da equipe, a issue entra para o roadmap. Um membro da equipe é atribuído como responsável e a solicitação de mudança é devidamente priorizada e adicionada ao planejamento da release.

Implementar

O desenvolvedor atribuído a issue realiza as devidas alterações/implementações no código e os respectivos testes, respeitando as convenções da comunidade. Assim que o código estiver adequado para revisão, e apto para o merge (sem conflitos), um pull request deve ser aberto. E a label revisão adicionada ao PR.

Continuous Integration (CI)

Todo pull request enviado ao repositório passa pelo processo de integração do travis, sendo necessário que a build passe em todos os testes para que o pull request siga para revisão.

CodeReview

Um membro da equipe é atribuído a revisão do código(reviewer) e deve:

  • Manter uma comunicação clara, dando o máximo de detalhes nos seus comentarios;
  • Pontuar aspectos positivos e negativos sobre o codigo;
  • Ter uma boa compreensão da modificação proposta(corrige um bug, melhora uma funcionalidade ou parte do código);
  • Utilizar o botão de review changes do github para comentar, aprovar ou solicitar alterações nos commits.
  • Levar em conta que uma boa solução para um problema hoje é geralmente melhor do que uma solução perfeita amanhã. Entretanto, uma gambiarra hoje é geralmente pior do que uma boa solução amanhã. Na dúvida, solicite a opinião de outras pessoas.

A revisão deve avaliar aspectos como:

  • A mudança se enquadra no propósito declarado pela contribuição;
  • É válida dentro da arquitetura existente do projeto;
  • Introduz possíveis defeitos que causarão problemas futuros;
  • Segue as regras da casa;
  • É uma boa maneira de executar a função descrita;
  • Introduz qualquer risco de segurança ou instabilidade;
  • e demais aspectos que julgar necessário.

Caso a alteração seja aprovada, o reviewer deve aceitar o pull request e atribuir um deployer a issue.

Deploy em homologação

Uma vez que a modificação proposta pelo pull request seja integrada ao branch master, o deployer deve realizar o merge do branch master no branch da release em andamento adicionando a tag apropriada. Em seguida realizar o deploy da aplicação tornando-a disponível para homologação no endereço https://stage.openredu.com

Aprovação (Q&A)

Nesse momento o membro do core responsável pelos testes de aceitação deve avaliar a modificação testando o uso da funcionalidade e avaliando os critérios funcionais, não funcionais e de performance, para em seguida e fazer o aceite ou recusa do que foi implementado.

Deploy em produção

Será realizado o Deploy no https://openredu.ufpe.br, fechando a solicitação

Cheatsheet

Cheatsheet-de-contribuição

Muito Obrigado!

A comunidade Openredu é grata pelo seu envolvimento! Esperamos que você se divirta com o código do Openredu. Caso ache algo difícil de descobrir, avise-nos para que possamos melhorar nosso processo ou documentação!

Créditos

Valendo-se da máxima de lavoisier e do espírito de compartilhamento do software livre, esse guia foi inspirado em boas práticas adotadas por comunidades notáveis(gitlab, discourse, jquery, jekyllrb, bootstrap, gnome, mozila, openstack, angula.js, liferay) e bastante googleing.

You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.