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

This guide assumes that you’ve read Instalar o Git and that you’ve already setup your machine with a Git client of your choice.

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.

Repo Overview

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:

  1. fork no projeto à sua escolha
  2. Clone-o para a sua máquina local
  3. Crie um novo branch
  4. Faça as alterações desejadas
  5. Verifique se tudo funciona
  6. Faça commit das alterações
  7. Sincronize-as com o GitHub
  8. Proponha as alterações em um PR ao repositório da SpongePowered
  9. Altere seu PR se necessário
  10. Seu PR é enviado para o master pela staff

Detalhes por favor!

1. Forking a Repo

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

All branches from the original repository will get forked too, you receive an exact clone of the forked repo.

Repo forking

2. Cloning the Fork to Your local Machine

Now you need to get this fork to your local machine to make your changes. Open the Git Client of your choice (Instalar o Git) and clone your fork to your local machine. The client will ask you for a folder to store everything in. Second step finished, well done!

Nota

Most steps can be done via GUI of your choice. If you’re experienced with a command line interface, then you can use it too. Each step will show you the required commands to achieve the desired result.

Alternatively, you can do this via CLI (command line interface, CMD or powershell on windows). Note that you need to create the folder everything is getting cloned to yourself before typing this command:

git clone git://github.com/YourGitHubAccount/ClonedRepoName.git
Repo cloning

3. Creating a New 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
Branches

Agora é hora de fazer suas alterações. Use o editor ou IDE à sua escolha para isso.

4. Test if Your Changes Work

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. Commit the Changes

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á!

Committing

6. Sync to 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
Pushing commits

7. Propose the Changes in a PR to the SpongePowered Repo

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.

PRs

8. Amend Your PR if Necessary

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. Your PR Gets Pulled

É isso. Estamos prontos! Ótimo trabalho!

Git avançado

Fundindo com rebase

Let’s say you have finished your additions to the repo, and let’s pretend that you made 137 commits while getting it done. Your commit history will certainly look cluttered. It would be a shame if they were all recorded into the repo, wouldn’t it? Too many trivial commits also clutters the project commit history. Fortunately, Git has a nice tool to circumvent this, it’s called a rebase. Rebasing can take your 137 small commits and just turn them into one big commit. Awesome, isn’t it? Instead of reinventing the wheel, we’ll just pass you a link to a very short and easily understandable squashing tutorial:

Gitready: fundindo com o *rebase*

Isto é o que ele faz, bem visualizado:

Squashing commits

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.

Setting up a remote

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. Fetch the Changes on the Remote Repo

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. Merge Remote Changes locally

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:

Rebasing 1

3. Rebase Local Branch against Updated Master

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:

Rebasing 2

4. Push Everything to your 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
Rebasing 3

Você conseguiu, incrível! Bom trabalho e bem feito, obrigado por voar na Rebase-Air!