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.

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 justes 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.

Cadastre-se no GitHub

1 - Para criar uma conta no GitHub, acess http://www.github.com, clique em “princing em signup”, e escolha a opção “free for open source” para criar sua conta gratuitamente. Nota: lembre-se que as contas gratuitas do GitHub se destinam a projetos OpenSource e por isso os seus repositorios estarão abertos a qualquer interessado.

2 - Uma vez criada sua conta, e estando logado, vá para o repositorio 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 em sua maquina local

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 usa 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"

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.

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 [email protected]:"<seu nome no GitHub>/nfephp.git"

Esse comando ira registrar qual é o endereço deo repositório no GitHub. Quando você "forkou" 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.

Autenticação no GitHub

Agora você tem que 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. Para isso temos que acessar a página do GitHub e clicar em "Account Settings", no icone com as ferramentas no lado direto da página (perto do seu login). Nessa página com seus dados cadastrais selecione "SSH Keys" e em seguidas em "Add SSH Key", coloque um titulo para sua chave e cole a chave no campo "key".

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 Key", será solicitada a digitação da sua senha, digite e envie, pronto sua chave digital já foi enviada e registrada em seu cadastro e agora podemos continuar.

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 pull origin master

Esse comando "puxa" todo o conteúdo do repositório remoto (GitHub) para usa 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.

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.

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.

git push origin master

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".

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

Mantendo seu repositório sincronizado com o o do mantenedor

git checkout -b upstream/master
git remote add upstream git://github.com/nfephp-org/nfephp.git
git pull upstream master
git checkout master
git merge upstream/master