Como Git(Hub)

Se queres ajudar a criar o Spronge, se tens uma adição incrível a fazer à API, ou queres melhorar a nossa documentação, então vias precisar de te familiarizar com o git e com o GitHub. Se já estás à vontade com branches, forking, issues, pull-requests e commits, então podes passar ầ frnte este tópico. Se não fazes ideia do que estamos aqui a falar, continua a ler.

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 do GitHub

O Git permite que muitos desenvolvedores diferentes desenvolvam um único pedaço de software ao mesmo tempo. O GitHub é um site onde os desenvolvedores podem colaborar e compartilhar os seus trabalhos com os outros. O GitHub usa o Git para a gestão deste trabalho.

Dica

Se não estás familiarizado com o vocabulário do Git e do GitHub, dá uma viste de olhos à página de glossário no GitHub (em inglês).

Neste caso, o repositório chama-se SpongePowered, tem duas branches, chamadas master e feature 1 e também alguns commits em ambas as 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 ficheiros. 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. Tu não podes simplesmente mudar o seu conteúdo, dado que o repo está em modo de leitura para os utilizadores comuns. Mas não penses que não é possível contribuíres! É aí que os forks entram em ação. Podes fazer uma cópia de qualquer repositório do SpongePowered, e fazer as tuas alterações nessa cópia. Quando tiveres a tua alteração concluída, submete-a como um pull request (PR) no nosso repositório. As tuas adições e alterações propostas poderão então ser revistas, e o staff dir-te-á se algo estiver errado, ou precisar de melhoramentos, de modo a culminar na aprovação do teu pedido (merge).

Aqui está um breve resumo do procedimento descrito acima, antes de entrarmos em detalhes:

1. Dá Fork ao repo que desejares

2. Clona-o para a tua máquina local

3. Cria um novo branch

4. Faz as alterações desejadas

5. Verifica se tudo funciona

6. Faz commit das tuas alterações

7. Sincroniza-as como GitHub

8. Propõe as modificações num Pull Request ao Repo SpongePowered

9. Corrige o teu PR, se necessário

10. O teu PR é enviado para o master pela staff

Detalhes, por favor!

1. Dar Fork a um Repo

Nota

Este passo só é necessário se não tiveres privilégios de push no repo que estás a alterar. Se estiveres a trabalhar num repositório teu, não precisas de fazer isto. Passa diretamente para o clone. Se estás a fazer alterações ao Sponge e não fazes parte da staff, então este passo é necessário.

Agora que sabes os conceitos básicos, vamos aos detalhes. Primeiro, tens de dar fork ao repo em que queres trabalhar. Isto pode ser feito no GitHub.com, onde encontrarás o botão Fork, na parte superior da página de repositórios. Depois de carregares aí, o GitHub vai fazer alguma magia e apresentar-te-á um clone do repo original. Repara que o clone está localizado em ``oTeuNickDoGitHub/NomeDoRepoClonado “. Excelente, primeira etapa concluída!

Nota

Todas as branches do repositório original serão igualmente clonadas, isto é, receberás uma cópia exata do repositório.

2. Clonar o Fork para a tua 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. Criar um novo Branch

Agora que você tem um clone local do seu garfo, é hora de criar um ramo para trabalhar. Os ramos foram destinados para poder evoluir e examinar diferentes recursos ou adições ao mesmo tempo, sem causar problemas e erros devido a interferências das adições. É altamente recomendado que você ** não** faça suas alterações no ramo `` master``. Em vez disso, crie um novo ramo você mesmo (com um nome sensível) e faça as mudanças lá.

Isso implica que precisamos de criar um `` ramo`` primeiro, então vamos! Você pode fazer isso através do seu cliente (deve haver um botão `` criar ramo`` 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

Chegou a hora de fazeres as tuas alterações. Usa o editor ou IDE que preferires para fazer isto.

4. Testar se as tuas alterações funcionam

For SpongeAPI and the implementations you have to run gradle compileJava. Proceed to the next step if it finishes without errors. If it doesn’t, make the appropriate corrections and try again.

Para SpongeDocs você pode enviar seu PR. Ele será construído automaticamente e revelará possíveis erros. Outra opção é criar o Docs localmente. Dê uma olhada no Readme.md no Docs para mais instruções.

5. Fazer 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:

First collect all files and folders you want to put into a commit:

git add <file>
git add <folder>

Now that the files are added to your list of changes you want included in the commit, just do

git commit

It will open a text window, where you can add a message if you desire. Have a look at the image below. You’ll notice that your commits are still stored locally only and not on your fork on GitHub.

Nota

Você pode ter vários compromissos em um PR. Apenas vá em frente e mude tudo o que precisa e comprometa as mudanças. Você pode combinar os compromissos em uma única zona mais tarde.

So now, the sixth step is done. Almost there!

6. Sincronizar com o GitHub

Agora precisamos obter as mudanças em seu garfo no GitHub. Tudo o que você fez até agora só é armazenado localmente agora. Como sempre, você pode usar seu cliente git para fazer isso (há um botão em algum lugar em sua GUI), ou você pode fazê-lo através da CLI:

git push <remote> <branch>

Neste caso, deverá ser:

git push origin feature/YourFeature

7. Propõe as modificações num Pull Request ao Repo 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. Corrige o teu PR, se necessário

Se quiseres fazer alterações ao teu PR, basta fazeres mais commits para a branch criada acima. Os commits subsequentes serão adicionados ao teu PR automaticamente.

9. O teu PR é aceite

Está feito. Tudo pronto! Excelente trabalho!

Git Avançado

Squashing 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: Squashing com Rebase

Isto é o que ele faz, muito bem visualizado:

Configuração de um Remote

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.

Alright. This step is done through CLI as most GUIs are missing this (rather advanced) functionality:

git remote add upstream https://github.com/ORIGINAL_OWNER/ORIGINAL_REPOSITORY.git

If you’re unsure if that worked as intended or if you want to check which remotes are currently set, you can check via:

git remote -v

the output should look like:

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

If you see the warning fatal: The current branch YourBranchName has no upstream branch., then the branch may not be on the upstream remote. This may happen if this is the first time you are pushing a commit for the new branch. To push the current branch and set the remote as upstream, use git push --set-upstream origin YourBranchName.

Rebasing

Let’s say you made some changes to your desired branch, but in the meantime someone else updated the repo. This means that your fork and your clone are outdated. This is not a big problem, but to avoid problems when merging your additions later on, it’s strongly advised to rebase your changes against the latest changes on the original repo. If you haven’t set up the remote repo yet, do it before trying to rebase.

A successful rebase requires several steps:

1. Fetch the Changes on the Remote Repo

First you need to fetch the changes on the remote repository. This is (again) done via CLI:

git fetch upstream

This will add all changes from the remote upstream and put them into a temporary upstream/master branch.

2. Merge Remote Changes locally

Now we need to select our local master branch:

git checkout master

After that we’ll merge the changes that are included in upstream/master into our local master branch:

git merge upstream/master

Muito bem, fizemos isto até agora:

3. Rebase Local Branch against Updated Master

Next up is rebasing the local branch you’re working in against local master. We need to switch to your working branch (here: feature/yourfeature) and then perform a rebase. This is done via:

git checkout feature/yourfeature
git rebase master

This will rewind your branch, add the commits from master and then apply your own changes again. The result looks like this:

4. Push Everything to your Fork

The last thing we need to do is to push everything to the fork. If you’ve already created a PR, it will get updated automatically:

git checkout master
git push -f
git checkout feature/yourfeature
git push -f

You made it, awesome! Good job and well done and thanks for flying Rebase-Air!