Como utilizar o Git(Hub)
Se você quer auxiliar na criação do Sponge, tem uma ótima adição a API, ou quer melhorar nossa documentação, precisará familiarizar-se com o git e GitHub. Se já está familiarizado com os processos de forking, branches, issues, pull requests e commits, então pule esse tópico. Se você não tem ideia do que estamos falando, então continue lendo.
Nota
Este guia assume que já leste Instalar o Git e que já configuraste um cliente Git, à tua escolha, na tua máquina.
O conceito básico do Git e GitHub
O Git permite que vários desenvolvedores possam desenvolver um software ao mesmo tempo. O GitHub é um site onde desenvolvedores podem colaborar e compartilhar seu trabalho com outros. Ele se baseia em Git para o gerenciamento do trabalho mencionado.
Dica
Se você não está familiarizado com o vocabulário do Git e do GitHub, dê uma olhada no Glossário do GitHub.
Neste caso, o repositório está nomeado como SpongePowered, tem dois branches chamados master e feature 1 e também alguns commits em ambos os branches.
Coloquemos estes conceitos em contexto - a começar pelo repositório. O repositório (abrev: repo) é o lugar onde um projeto guarda os seus arquivos. O repositórios do SpongePowered estão no GitHub. No entanto, este repositório tem algumas restrições para o proteger de edições maliciosas ou não desejadas. Você não pode simplesmente mudar o seu conteúdo, dado que o repositório está em modo de leitura para os utilizadores comuns. Mas não pense que não é possível contribuir! É aí que os forks entram em ação. Você pode fazer uma cópia de qualquer repositório do SpongePowered, e fazer as suas alterações nessa cópia. Quando concluir sua alteração, envie-a como um pull request (PR) no nosso repositório. As suas adições e alterações propostas poderão então ser revistas, e o staff dirá a você se algo estiver errado, ou precisar de melhorias, de modo a culminar na aprovação do teu pedido (merge).
Aqui há um pequeno sumário do procedimento descrito acima, antes de irmos em detalhes:
Dê fork no projeto à sua escolha
Clone-o para a sua máquina local
Crie um novo branch
Faça as alterações desejadas
Verifique se tudo funciona
Faça commit das alterações
Sincronize-as com o GitHub
Proponha as alterações em um PR ao repositório da SpongePowered
Altere seu PR se necessário
Seu PR é enviado para o master pela staff
Detalhes por favor!
1. Dando fork em um repositório
Nota
Este passo só é necessário se você nao tem permissao de push no repo que você está alterando. Se você está trabalhando no seu próprio repositório, não é necessário um fork. Apenas pule essa etapa e clone direto. Se você está alterando o Sponge e você não é da staff, essa etapa é necessária.
Agora que você sabe o conceito básico, iremos discutir os detalhes. Primeiro você precisa fazer fork no repositório que você quer alterar. Isso pode ser feito no GitHub.com, onde você irá encontrar o botão Fork no topo da página dos repositórios. Após pressioná-lo, o GitHub vai lhe apresentar um clone do repositório original. Você notará que o clone agora estará localizado em SuaContaDoGitHub/NomeDoRepoClonado. Pronto, primeiro passo completo.
Nota
Todas as branches do repositório original serão igualmente clonadas, isto é, receberás uma cópia exata do repositório.
2. Clonando o fork para dua máquina local
Agora tens de passar este fork para a tua máquina local para fazer as alterações. Abre o cliente de Git que escolheste escolha (Instalar o Git) e dá clone ao teu fork para a tua máquina. O cliente vai perguntar-te em que pasta queres guardar tudo, escolhe um lugar da tua conveniência. Segunda etapa terminada, muito bem!
Nota
A maioria dos passos pode ser feito via GUI à tua escolha. Se tens experiência com uma interface de linha de comando, podes usar isso também. Cada passo mostrará os comandos necessários para alcançar o resultado desejado.
Em alternativa, podes fazer isto via CLI (command line interface, CMD ou powershell no Windows). Nota que precisas de criar a pasta para onde tudo vai ser clonado antes de correres este comando:
git clone git://github.com/YourGitHubAccount/ClonedRepoName.git
3. Criando uma nova branch
Agora que você tem um clone local do seu fork, está na hora de criar uma branch para trabalhar. As branches foram projetadas para se desenvolver e testar diferentes recursos e adições ao mesmo tempo, sem causar problemas e erros devido à interferência das adições. É fortemente aconselhável de que você não faça alterações no branch master. Em vez disso, crie uma nova branch (com um nome razoável) e faça as alterações lá.
Isso implica que primeiro precisamos criar uma branch, então vamos lá! Você pode fazer isso pelo seu cliente (onde deve ter um botão de criar branch em algum lugar), ou você pode usar o CLI com git:
git checkout -b [name_of_your_new_branch]
This will create a branch with the name of your choice and switch to it. All changes you’re about to make will be
on this branch. If you need to switch to another branch (for example master), just reuse this command. Third step
done! Good job so far! To get an overview of your branches, just have a look at your git client or use:
git branch
Agora é hora de fazer suas alterações. Use o editor ou IDE à sua escolha para isso.
4. Teste se suas alterações funcionam
Para a SpongeAPI e as implementações você precisa executar gradle compileJava. Siga para o próximo passo se finalizar sem erros. Se não, faça as correções necessárias e tente novamente.
Para a SpongeDocs você pode apenas enviar sua PR. Será feito uma build automaticamente e revelará possíveis erros. Outra opção é fazer um build do docs localmente. Dê uma olhada no readme.md em docs para mais instruções.
5. Faça commit das alterações
When you’re done, you need to bundle them into a single package (a commit) and get them into the branch. Again, your
git client will help you out. Add a meaningful name to your commit and a short description if needed. This can be done
via CLI too:
Primeiro colete todos os arquivos e pastas que você quer colocar em um commit:
git add <file>
git add <folder>
Agora que os arquivos foram adicionados na lista de alterações que você quer inclusas no commit, apenas faça
git commit
Abrerá uma janela de texto onde você pode colocar uma mensagem se desejar. Dê uma olhada na imagem abaixo. Você notará que seus commits ainda estão apenas salvos localmente e não no seu fork no GitHub.
Nota
Você pode ter multiplos commits em uma PR. Apenas vá em frente e altere tudo oque precisar e comite as alterações. Você pode juntar tudo em um único commit depois.
Agora, o sexto passo está completo. Quase lá!
6. Sincronizar com o GitHub
Agora precisamos colocar as alterações do seu fork no GitHub. Tudo o que você fez até agora está salvo localmente. Como sempre, você pode usar seu cliente git para fazer isso (há um botão em algum lugar da sua interface gráfica), ou você pode fazer isso via CLI:
git push <remote> <branch>
Neste caso deve ser:
git push origin feature/YourFeature
7. Propor as alterações em uma PR ao repositório da SpongePowered
You can either go to your forks page on GitHub.com (there should be a notice at the top of your forks page to guide you), or you can use your GitHub client to create a pull-request. The official GitHub for Win client uses the top right corner of the window for this.
8. Altere sua PR se necessário
Se quisermos que você faça alterações na sua PR, então apenas faça mais commits no branch criado acima. Mais commits serão automaticamente adicionados a sua PR.
9. Sua PR é puxada
É isso. Estamos prontos! Ótimo trabalho!
Git avançado
Fundindo com rebase
Digamos que terminaste as tuas adições ao repo, e vamos supor que fizeste 137 commits ao fazer isso. O teu histórico de commits estará enorme e desorganizado. Seria uma pena se todos fossem gravados no repo, não é? Demasiados commits triviais também obstruem o histórico de commits do projeto. Felizmente, o Git tem uma ótima ferramenta para contornar isto, chamada rebase. O Rebase pode transformar os teus 137 pequenos commits num só grande commit. Impressionante, não é? Em vez de reinventar a roda, fornecer-te-emos um link para um tutorial de squashing muito curto e facilmente compreensível:
Gitready: fundindo com o *rebase*
Isto é o que ele faz, bem visualizado:
Criando um remoto
Naturally the original repo is the direct parent of your fork and your fork is the direct parent of your local clone. However, the original repo isn’t the direct parent of your clone. This isn’t a problem in the first place, but it prevents you from updating your clone to the latest changes on the original repo. If you setup the original repo as a remote (read: “parent”) of your clone, you’ll be able to grab all changes made to this repo and apply it to your local clone. Look below to see how grabbing and updating works.
Tudo bem. Este passo é feito através de CLI já que a maioria das GUIs (interfaces gráficas) estão faltando essa funcionalidade (bastante avançada):
git remote add upstream https://github.com/ORIGINAL_OWNER/ORIGINAL_REPOSITORY.git
Se você está inseguro sobee se isso funcionou como o esperado ou se você quer checar quais remotos estão definidos, você pode checar via:
git remote -v
a saída deve parecer assim:
origin https://github.com/YOUR_USERNAME/YOUR_FORK.git (fetch)
origin https://github.com/YOUR_USERNAME/YOUR_FORK.git (push)
upstream https://github.com/ORIGINAL_OWNER/ORIGINAL_REPOSITORY.git (fetch)
upstream https://github.com/ORIGINAL_OWNER/ORIGINAL_REPOSITORY.git (push)
Nota
Se você ver o aviso fatal: The current branch NomeDaSuaBranch has no upstream branch., então a branch pode não estar no upstream remoto. Isso pode acontecer se é a primeira vez que você envia um commit para a nova branch. Para enviar a branch atual e definir o remoto como upstream, use git push --set-upstream origin NomeDaSuaBranch.
Rebasing
Digamos que você tenha feito algumas mudanças na sua branch desejada, mas ao mesmo tempo alguem atualizou o repo. Isso significa que seu fork e seu clone estão desatualizados. Isso não é um grande problema, mas para evitar problemas quando mesclar adições mais tarde, é fortemente recomendável fazer rebase das suas alterações com as últimas mudanças do repo original. Se você ainda não definiu o repo remoto ainda, faça antes de tentar fazer rebase.
A successful rebase requires several steps:
1. Encontrar as mudanças no repo remoto
Primeiro você precisa buscar as alterações no repositório remoto. Isso é (novamente) feito via CLI:
git fetch upstream
Isso vai adicionar todas as alterações do upstream remoto e colocá-las em um branch upstream/master temporário.
2. Fundir as alterações remotas localmente
Agora precisamos selecionar nosso branch master local:
git checkout master
Depois disso vamos fundir as alterações que estão inclusas em upstream/master em nosso branch master local:
git merge upstream/master
Tudo bem, isto é oque fizemos até agora:
3. Fazer rebase no branch local com o master atualizado
Em seguida fazer rebase do branch local em que você está trabalhando com o master local. Precisamos alternar para a sua branch de trabalho (aqui: feature/seurecurso) e então executar o rebase. Isso é feito via:
git checkout feature/yourfeature
git rebase master
Isso vai rebobinar sua branch, adicionar os commits da master e então aplicar suas próprias alterações novamente. O resultado será parecido com este:
4. Enviar tudo ao seu fork
A última coisa que precisamos fazer é enviar tudo ao “fork”. Se você já criou uma PR, vai ser atualizada automaticamente:
git checkout master
git push -f
git checkout feature/yourfeature
git push -f
Você conseguiu, incrível! Bom trabalho e bem feito, obrigado por voar na Rebase-Air!
