Contribuindo usando o GitHub

Para contribuir com código, a forma mais adequada é usar o GitHub e o git ao invés de enviar as correções via email ou para a lista de discussões.

No GitHub existem várias branchs e tags, as principais são:

master - aqui está o código atual, em master devemos apenas corrigir BUGS e incluir apenas funções necessárias ao funcionamento da API. Ou seja, não introduzir novas funcionalidades.

develop - aqui estão as classes refatoradas e sendo refatoradas é o ambiente de testes, onde o desenvolvimento de novas funcionalidades e estruturas é feito.

Sempre que uma nova versão sair de develop para master o que está em master irá passar para uma nova branch ou tag, para referencia de versões anteriores. Essas versões são causadas principalmente por alterações nos padrões da SEFAZ.

O Git é uma ferramenta com enorme quantidade de recursos, e funciona muito bem em linha de comando e é dessa forma que devemos utiliza-la, tanto no Linux como no Windows. Não vou dizer que é "simples" mas também não é nenhum "bicho de sete cabeças".

Para poder começar a colaborar usando o Git, alguns cadastros, instalações e ajustes devem ser feitos para preparar o ambiente para o sistema de versões e alguns conceitos deverão ser entendidos, mas isso pode ser feito aos poucos.

Referências:

http://gitref.org

http://git-scm.com

http://tom.preston-werner.com/2009/05/19/the-git-parable

Cadastre-se no GitHub

Para criar uma conta no GitHub, acesse https://github.com/join. Nota: lembre-se que as contas gratuitas do GitHub se destinam a projetos OpenSource e por isso os seus repositórios estarão abertos a qualquer interessado.

Crie um FORK do projeto

Uma vez criada sua conta, e estando logado, vá para o repositório do nfephp-org/nfephp e clique no botão "Fork", isso irá criar um "Fork" (cópia) do projeto original para o seu repositório no GitHub (em seu nome).

Instalando o Git no seu computador

Se você é um usuário do Linux (Debian ou Ubuntu), abra um terminal e digite:

sudo apt-get install git-core

Se você é um usuário do Windows, ai dá um pouco mais de trabalho:

Vá ao site oficial do git em http://git-scm.com e baixe o “installer” para windows. Inicie a instalação e como de costume vá indicando "Next" até a seção "Select Components"

IMPORTANTE: selecione "Git Bash Here", continue e na proxima tela selecione "Use Git Bash Only" na janela seguinte selecione "Checkout as-is, commit Unix-style line endings", termine a intalação. Parabéns ! você agora tem o Git instalado em sua máquina.

Configurando e clonando o repositório para sua máquina local

Agora devemos criar uma pasta na máquina local onde será clonado o repositório do GitHub (aquele que você já "forkou") e configurar o Git.

Crie uma pasta no local desejado, se usar o windows clique com o botão direito do mouse sobre o diretório criado e selecione "Git Bash Here", isso vai abrir uma janela de terminal onde iremos fazer as configurações e onde os comandos serão inseridos (lembre-se vamos usar o Git com linha de comando).

Configurações

Na janela do terminal digite:

git init

Esse comando irá criar toda a estrutura de dados do Git para a gestão de versões em um diretório oculto ".git"

git config --global user.name "seu nome"
git config --global user.email "seu email"
git config --global color.ui auto

Estes comando irão configurar o seu nome e email para envio das alterações, são sua identificação no GitHub, essas informações ficarão registradas no arquivo config do Git, e por isso são necessárias apenas uma vez. O último desses comandos coloriza a saída dos comandos para facilitar a legibilidade.

git config --global diff.renamelimit "0"

Este comando previne problemas de falta de memória, vamos lembrar que quem usa o Git é desenvolvedor e em geral tem máquinas adequadas (com memória e espaço de disco suficientes).

ssh-keygen -t rsa -C "seu email"

Esse comando cria uma chave digital para o acesso seguro ao GitHub (por SSH) e será mais útil para os usuários do Windows, os usuários do Linux e que usam o SSH já tem sua chave criada no diretório cd ~/.ssh. Somente é necessário usar esse comando uma única vez, para criar a chave.

git remote add origin git@github.com:"<seu nome no GitHub>/nfephp.git"

Esse comando irá registrar o endereço do repositório no GitHub. Quando você "forkou" (clonou) o repositório do mantenedor no GitHub, foi criado um repositório em seu nome, você pode pega-lo diretamente na sua página no GitHub. Quando você for fazer um "commit" de uma alteração, essa alteração será enviada para esse endereço. Como nos outros comandos anteriores não será necessário repeti-lo.

Mais informações sobre repositórios remotos: https://git-scm.com/book/pt-br/v1/Git-Essencial-Trabalhando-com-Remotos

Autenticação no GitHub

Agora você deve se autenticar no GitHub, para isso é necessário que você registre a sua chave digital que será usada na comunicação segura entre sua máquina e o serviço no GitHub. Ou seja, a chave é uma forma segura do GitHub identificar o seu computador, sem a necessidade de uma senha. Acesse https://github.com/settings/keys e clique no botão "New SSH key", informe um título para sua chave e cole a chave no campo "key". O título serve para identificar de forma amigável o seu computador.

Para colar a chave você deve tomar alguns cuidados, em Windows você pode usar o NOTEPAD para abrir a chave e ai copia-la.

notepad ~/.ssh/id_rsa.pub 

Em Linux tem muitas opções mas pode usar

gedit ~/.ssh/id_rsa.pub

Copie e cole sem mudar ABSOLUTAMENTE nada e clique em "Add SSH Key", será solicitada a digitação da sua senha do GitHub, digite e envie, pronto sua chave digital já foi enviada e registrada em seu cadastro e agora podemos continuar.

Se você ainda não tem uma chave SSH acesse https://help.github.com/articles/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent para mais informações.

Clonando o repositório "forkado" para a pasta local

Para copiar o repositório remoto (no GitHub) para o seu repositório local (a pasta criada) use o comando abaixo

git checkout master
git pull origin master

Esse comando "puxa" todo o conteúdo do repositório remoto (GitHub) para sua pasta local. Se tudo correu bem você agora pode ver todos os arquivos sendo baixados. Agora temos condições de contribuir com alterações e correções no código. Repita para develop

git checkout develop
git pull origin develop

Nota: Não use esse diretório como base para seus testes faça uma cópia de trabalho e quando estiver satisfeito com as mudanças copie-as para esse diretório, para evitar sujeira e erros.

Carregando o repositório origem do projeto

Para manter seu fork atualizado é necessário configurar um branch "upstream" com o repositório origem do seu fork, ou seja, o repositório original do projeto NFePHP. Para adicionar mais um repositório remoto faça:

git remote add upstream git@github.com:nfephp-org/nfephp.git
git fetch upstream

Desta forma, "origin" significa o repositório remoto do seu fork, e "upstream" significa o repositório original do NFePHP (estes nomes são convenções do Git). IMPORTANTE: sempre antes de iniciar qualquer modificação atualize seu fork:

git checkout master
git fetch upstream
git merge upstream/master
git push origin master

git checkout develop
git fetch upstream
git merge upstream/develop
git push origin develop

Contribuindo com código

Faça as correções, alterações e mudanças que desejar e as coloque nessa pasta (nosso repositório local). Usuários do windows devem atentar para alguns cuidados :

Não usar TABULAÇÃO no código (substitua por 4 espaços)

Usar a quebra de linha no padrão Unix (apenas um LF)

Os arquivos devem estar com charset UTF-8 SEM BOM

Se não estiver assim qualquer submissão será recusada !!!!

Para fazer uma submissão use os seguintes comando no git (após as correções terem sido feitas é claro)

git add .

Esse comando carrega todas as alterações feitas. No lugar do ponto você pode indicar um arquivo em especifico.

git commit -m "[UPD] seu comentário, seja o mais claro possível sobre o que mudou."

Esse comando "commita" essas alterações e anexa o seu comentário.

SOCORRO ! Cometi um erro !!!

git reset --hard HEAD~1

Se você tiver cometido um erro e queira remover seu "commit" e as alterações efetuadas mas ainda não enviadas para o GitHub, pode usar o comando acima.

git push origin master (ou develop)

Esse comando envia a alteração para o seu repositório no GitHub

Solicitando um "PULL REQUEST"

Agora que as alterações já foram enviadas para o seu repositório no GitHub é necessário solicitar que sejam inclusas no repositório do mantendor, para isso enviamos um "pull request" ao mantenedor.

Para isso vá a sua página no GitHub e clique em "Pull Request", será aberta uma página para que você descreva algum comentário para o mantenedor, preencha os campos e clique em "send Pull Request".

Pronto sua contribuição foi feita, agora depende no mantenedor aceita-la ou não.

Mantendo seu repositório sincronizado com o do mantenedor

git fetch upstream

Este atualiza o pacote original do mantenedor

git checkout master

Este comando retorna o git para o branch "master"

git merge upstream/master

Este comando "funde" o repositório do mantenedor com o seu repositório master local

Faça o mesmo apenas alterando master por develop caso esteja trabalhando com o diretório de desenvolvimento.