Então você quer contribuir com este projeto? Muito obrigado pelo seu interesse! Aqui estão descritos alguns padrões que são utilizados durante o meu desenvolvimento e que eu gostaria que você também seguisse. Então, vamos lá!
Possui algum problema? Você não precisa saber programação para ajudar neste projeto.
Abra uma nova issue e descreva os problemas encontrados da melhor maneira possível. Informe o passo-a-passo para gerar o problema, incluindo botões pressionados, screenshots de telas ou até dump de banco de dados.
Lembre-se de que a informação sobre o problema é um item precioso para solucioná-lo.
Este projeto é controlado com tags no formato de versionamento semântico e 2 branches principais: master
e develop
. Todas as tags representam ambientes estáveis e a última tag sempre aponta para o branch master
. Todos os branches saem do branch master
e retornam para o branch develop
. Quando uma tag é finalizada, todos os branches que não retornaram deverão sofrer um rebase para o branch master
.
Certo, mas o que isso quer dizer?
Eu tento sempre manter a melhor árvore Git possível neste projeto. Você pode visualizá-la acessando a linha de desenvolvimento do projeto. Conforme visualização, todos os branches saem da última tag e retornam antes da próxima tag. Assim, eu consigo ter uma linha de desenvolvimento concisa e de ótima visualização em softwares como o Gitk.
Lembre-se dessa estrutura! Ela é muito importante!
Somente 2 branches possuem nomes fora do padrão: o master
e o develop
. Todos os outros branches devem possuir o formato /^issue-[1-9][0-9]*$/
, representando o número da issue que gerou aquele branch. Portanto, todos os branches criados devem ser resultantes da abertura de uma issue no projeto. Descrevendo melhor, todos os branches devem iniciar com issue-
e finalizar com o número da issue que gerou aquele branch.
Por exemplo, se existe uma issue 42 que irá gerar uma alteração de código, o branch que será criado terá o nome issue-42
.
Como eu não utilizo um fork do projeto e efetuo commits diretamente, em alguns momentos você poderá encontrar branches neste padrão. Ignore, são os meus branches. Não utilize-os, eles são extremamente instáveis e podem causar uma fissão nuclear.
As tags obedecem ao versionamento semântico comum aos projetos opensource disponíveis. A última tag sempre será o projeto mais estável e todas elas apontarão para o branch master
.
Oba! Você quer contribuir? Então primeiramente, faça um fork deste projeto utilizando o próprio Github e faça um clone em seu ambiente de trabalho. Para desenvolvimento, eu utilizo uma máquina Vagrant neste projeto. Para inicializá-la, basta copiar o arquivo de configurações do Vagrant que está na distribuição e solicitar a sua criação.
cp Vagrantfile.dist Vagrantfile
vagrant up
Todo o projeto será inicializado e estará pronto para execução, acessível no endereço http://localhost:8000
. Também será instalado o PHPPgAdmin, disponível no endereço http://localhost:9000
.
Caso o Vagrant encontrar estas portas ocupadas, ele irá informá-lo quais são as novas portas definidas.
Se você possui algumas dúvidas com relação ao código-fonte e estrutura de classes, a API do Balance está disponível.
YEAH! Patch Request! Vamos lá!
Seguindo os padrões de estrutura do projeto, sempre faça um branch a partir do branch master
, nomeado no padrão /^issue-[1-9][0-9]*$/
. Efetue seus commits, sempre com a mensagem possuindo o padrão /^Issue #[1-9][0-9]*/
. Isto quer dizer que todos os seus commits devem possuir mensagens que iniciam com um texto que aponta para a issue relacionada ao branch. Isto faz com que o Github referencie os commits com a issue, facilitando a navegação.
Se você alterar o código-fonte do projeto, por favor, crie um teste unitário que faça 100% de coverage em suas alterações. Assim, vamos garantir que este projeto poderá rodar em futuras versões do PHP. Para executar os testes unitários no projeto, basta executar o PHPUnit disponível na instalação.
php vendor/bin/phpunit
Se sua alterações forem para novos recursos, os famosos enhancements, crie um teste unitário com o mesmo namespace de suas novas classes. Por exemplo, se você criar uma classe nova chamada Balance\Model\Persistence\FooBar
, crie um novo arquivo na estrutura de testes chamado module/Balance/test/Balance/Model/Persistence/FooBarTest.php
com uma classe chamada Balance\Model\Persistence\FooBarTest
.
Todavia, se você está corrigindo um bug que está descrito na issue 42, crie um arquivo na estrutura de testes chamado module/Balance/test/Balance/Bug/Issue42Test.php
com uma classe chamada Balance\Bug\Issue42Test
, que force a execução do bug informado. Altere o código até que este bug seja solucionado.
O banco de dados possui uma estrutura gerenciada pelo Phinx através de migrations. Para criar uma nova migration, utilize o seguinte comando.
php vendor/bin/phinx create AlterTableFooAddBar
Tente nomear a migration conforme o padrão das criadas anteriormente. Particularmente, não possuo padrões para isto.
Lembre-se de sempre criar migrations que consigam subir e descer versões corretamente, alterando e retornando alterações num formato que minimize a perda de informações em ambientes de produção.
Depois que você enviar suas alterações para o Github, este projeto utiliza o Travis CI para analisar o código. Inúmeros testes serão feitos, principalmente de padronização de código. Somente quando você receber um status passing, crie o PR.
Eu só vou aceitar PR que contenham todos estes requisitos! Poxa, eu estou tentando criar um projeto legal, então vamos criar uma estrutura legal, certo?
Todos os retornos de branches terão uma mensagem com o nome do branch utilizado para retorno. Isto quer dizer que vamos saber todos os pontos onde todos os branches sairam e retornaram. Simples assim.
Como eu utilizo o repositório original para envio de novos branches, normalmente faço os seguintes comandos para a alteração de código-fonte da issue 42.
git remote update --prune
git checkout master
git merge origin/master
git checkout master -b issue-42
Faço as alterações necessárias e para cada commit faço os seguintes comandos.
git add -A
git commit -m'Issue #42 Resposta da vida, universo e tudo mais.'
Depois envio as alterações para o Github, que informará o Travis CI e este executará os testes unitários.
git push origin issue-42
Tudo certo? Feito! Vamos reintegrar o branch no develop.
git remote update --prune
git checkout develop
git merge origin/develop
git checkout issue-42
git rebase develop
git checkout develop
git merge --no-ff issue-42
git push origin develop
Sim, faço merges com --no-ff
para criar um novo nó na árvore de versionamento.
Fechando versão? Então faço um merge no branch master
do develop
sem utilizar o --no-ff
.
git remote update --prune
git checkout develop
git merge origin/develop
git checkout master
git merge origin/master
git merge develop
git push origin develop master
Simples?
Todos estes passos são necessários para mantermos um padrão. Sei que tudo isto parece complicado, mas foi a maneira mais simples que encontrei para manter todo o código-fonte padronizado.
Tens alguma dúvida? Entre em contato! Abra uma issue. Comente.
Happy Coding!