Usando GitLab com GitKraken

Conectando o repositório do GitLab no GitKraken

Criando e unindo contas

• Vá para ( https://gitlab.com/users/sign_in ) e crie uma conta se não tiver.

Um projeto da USP Game Dev

Caso você queria fazer um projeto da USP Game Dev, é interessante você criar ele dentro do nosso grupo do Gitlab:

• Vá para o grupo do gamedev no discord ( mais informações )
• Encontre o Will lá e mande mensagens para ele até ele te adicionar no grupo da gamedev do gitlab.

Continuando

• Agora vá para o site do GitKraken e baixe ele.

• Abra o GitKraken, procure o botão de login no canto superior direito e entre em sua conta.

• Vá para as preferências do GitKraken -> Authentication -> GitLab -> Connect to GitLab.

• Autorize o GitKraken.

• Caso você não tenha uma SSH Key, clique em “Generate SSH Key and add to GitLab".

• Pronto, agora você deve estar com o GitKraken pronto para clonar o seu repositório.

Conectando o repositório no GitKraken

• Dentro do GitKraken, clique na pequena pasta no canto superior esquerdo.

• Selecione “Clone” -> GitLab.com. Escolha a pasta onde você irá guardar os dados do projeto, e logo abaixo selecione o seu projeto ( no exemplo, Spookmin) e clique em “Clone the Repo!”.

• Pronto, agora você vai ver a tela do repositório, onde toda poderá realizar a maioria das ações do gitlab.

Atualizando projeto

Sobre Issues, Branches e Merge Requests

• Issues são coisas que devem ser feitas no projeto. Podem ser coisas a serem adicionadas, arrumar erros, refatorar o código, etc. Issues devem ser coisas simples de se fazer, caso contrário é uma boa ideia dividir a issue em menores ( ex: Ao invés de uma issue “Fazer o player”, troque para “fazer um boneco que se mexe”, “adicionar ataques ao boneco” e “adicionar vida”, etc. )

• Branches são “ramos” do projeto. Basicamente são versões paralelas dele. Em geral, quando queremos modificar algo nele, abrimos uma branch, modificamos ela e depois solicitamos um MR.

• Merge Requests (ou MRs) são pedidos para colocar as modificações de um branch do projeto no projeto ( literalmente “fundir” o branch com o main ). Geralmente MRs precisam de um approval antes de serem adicionados ( alguém ( além de quem fez o branch ) vai ter que ver se tudo está certo no branch )

Criando um novo branch

• Vá para a aba de issues no GitLab e procure uma Issue que você deseja fazer ou adicione uma se você achar necessário.

• Dentro dela, primeiramente veja se ninguém mais está cuidando dela no canto superior direito, “Assignee”. Caso não tenha ninguém, clique em “Assign Yourself” para garantir que duas pessoas não vão trabalhar paralelamente na mesma issue.

• Clique no grande botão verde “Create Merge Request”. Ele não vai só criar uma branch para você trabalhar, mas também vai preparar um MR para quando você tiver terminado.

• Duas coisas importantes para se notar aqui:
  • “WIP:” no começo do nome de um MR quer dizer “Work-in-progress” e significa que ele ainda não está terminado, o que bloqueia Merges prematuros.
  • “Closes #X” na descrição implica que esse MR resolve um determinado Issue de número X. Caso o MR seja aceito, a issue será automaticamente fechada.
• O seu branch deve aparecer no GitKraken agora. Clique duas vezes nele para fazer uma cópia para a sua maquina.

Commits e Push

• Garanta que você está no branch correto.
• Faça as modificações no projeto que achar necessário.
• Volte para o GitKraken.
• Você verá que existe uma nova linha em cima da sua árvore do projeto. Clique nela.

• Uma nova janela abrirá. Nela, o GitKraken mostrará todos os arquivos que foram modificados em comparação com o último commit que você realizou. Commits são mudanças que você realizou e “publicou”, isso é, você “staged” (confirmou) tais mudanças. Na nova janela do GitKraken, você pode confirmar as mudanças ( stage all changes ) ou descartar ( o lixo no canto superior esquerdo ) elas.

• Escreva um Título para o seu commit ( como "Adicionei tal arquivo", "criei tal função", etc ). Uma descrição geralmente não é necessária se o título estiver claro o bastante. Após isso, clique em “Commit Changes to X Files”.

• Note como a sua árvore mudou!

• Commits em geral são curtos para garantir que você possa voltar com facilidade para uma versão anterior. Se você der commit em uma mudança inteira de uma vez ao invés de um commit a cada passo dela, se você precisar voltar uma versão, você vai perder tudo o que fez!
• Gere quantos commits precisar até achar que acabou.
• Mas todas essas mudanças ainda são locais. Você tem que dar um “Push”, que significa passar os seus commits locais para o repositório/branch na nuvem. Basta clicar no gigante botão “Push” do GitKraken.

• Note que agora o seu branch possui o símbolo do GitLab, indicando que as mudanças também estão no repositório.

Criando um Merge Requests

• Agora que você terminou a sua parte, basta fazer o MR.
• Na página de Merge Requests do GitLab, ou crie um MR novo ou selecione um previamente criado pela issue.

• Caso você queira criar um novo:
• Selecione o branch o qual quer dar merge e clique em “Compare branches e Continue”. Tome cuidado para dar merge no master e não em outro branch!

• Na nova página que abrirá, edite o MR como achar melhor. Em geral, escreva “Closes #X” na descrição, "Approvals required" em 1 e marque “Remove source branch when merge request is accepted”. Quando terminar, clique em “Submit Merge Request”.

• Caso você tenha criado o MR pela issue, edite ele para garantir que as opções acima estão marcadas.
• Após isso, clique no botão “Resolve WIP Status” para retirar o seu MR de Work-In-Progress e permitir merges.

• Espere pacientemente alguém ( que não seja você ) aprovar esse MR.

( O tempo passa )

• Espere alguém com write permission dar merge ou dê você mesmo.

• Pronto! As modificações do seu branch agora estão no master.

Atualizando o seus arquivos

Pulls

• Agora que você ( e, com sorte, seu grupo ) adicionaram coisas ao projeto, você precisa baixar as mudanças para a sua máquina.
• Volte para o GitKraken.
• Como você vai notar, o seu master está desatualizado!

• Troque o seu branch devolta para o master.

• Basta clicar em "Pull!".

• (Opcional) Delete o branch local: clique com o botão direito do mouse em cima dele e selecione Delete (nome do branch). Confirme.