Existem diferentes formas de contribuição em projetos open source, sendo uma das principais a contribuição de implementações através do Pull Request. Nesse guia, vou abordar como criar um Pull Request no projeto L2jOrg, mas que poderá ser usado em qualquer projeto que utilize git.
Eu trabalho com git há alguns anos, e durante esse tempo experimentei diversas formas de utilização. Um dos melhores fluxos de trabalho pra utilizar git, na minha opinião, é o modelo "short lived branches" ou "topic branches", nesse link você pode encontrar mais detalhes.
Requisitos para seguir o guia:
Git;
IDE (eu irei utilizar o IntelliJ IDEA, mas pode ser usada a que preferi);
Uma conta no github.
Obs.: a IDE é opcional, você pode utilizar apenas o cliente git para realizar os passos desse guia, mas por simplicidade será demonstrado apenas com o uso da IDE.
1º Passo - Criando um fork do projeto no github
O projeto L2jOrg utiliza submódulos, é necessário realizar o fork de todos os repositórios que pretende fazer contribuições.
A criação de um fork é bastante simples, apenas é necessário estar logado no github, e utilizar o botão fork na página dos repositórios:
Vamos criar o fork para o primeiro repositório: [Hidden Content]
Clique no botão fork no canto superior direito
Caso participe de alguma organização no github, aparecerá uma tela para escolher onde será criado o fork
Agora faça o mesmo processo para o repositório do Datapack: [Hidden Content].
Após feito o fork dos dois repositórios, você terá uma cópia dos repositórios.
2º Passo - Clonando seu repositório
Antes de seguir esse passo, é necessário ter o git instalado.
Após a criação do fork, iremos fazer o clone dos seus repositório. Esse clone nada mais é do que fazer uma cópia do seu repositório remoto, que está no github, para sua máquina. Assim, podemos modificar os arquivos com mais facilidade.
Para realizar o clone, precisamos saber qual o endereço dos nossos repositórios. Podemos encontrar essa informação no github:
Aqui teremos duas opções de url. Utilizando ssh ou https. Eu particulamente utilizo a com ssh por achar mais simples, já que utilizando https é necessário fornecer o usuário e senha do github para se comunicar com o repositório remoto. Caso queira utilizar ssh, mas não sabe como configurar, segue a documentação.
No botão "code" do github é onde podemos encontrar as urls necessárias para fazer o clone do repositório. Copie a url que iremos utilizar na IDE, no nosso caso no IntelliJ IDEA.
A primeira vez que o IntelliJ é aberto, é apresentada uma tela de "Bem Vindo". Apartir dessa tela já podemos realizar o clone do repositório, utilizando o botão "Get from VCS".
Se no seu caso, ele já abriu algum projeto que você não queira fechar, é só utlizar o menu "File" -> "New" -> "Project from Version Control"
Irá aparecer uma janela para colocar a url do projeto, após adicionar a url e escolher onde seu projeto vai ficar é só clicar em "clone".
Ao finalizar o clone, o IntelliJ abre a janela com o arquivos do projeto:
Algo que vale à pena mencionar é que mesmo sem ter feito o clone do Datapack, o Intellij realizou o clone automaticamente. Isso ocorre devido ao projeto utlizar submodules. Para mais detalhes veja esse artigo!
Vemos verificar o conteúdo dos repositório, para isso clique no nome da branch "development" no canto inferior direito. Aqui é mostrado as branches existentes no repositório.
Nesse caso, o Datapack está em um estado que chamamos de "detached head". Rudemente falando, esse estado indica que fizemos o checkout de um commit específico ao ínves de uma branch. Aqui você encontra mais detalhes!
Vamos "corrigir" esse estado fazendo o checkout da branch development. Clique em origin/development e checkout:
3º Passo - Configurando Remotes
Agora vamos para uma das mais importantes partes desse guia. Uma das maiores dificuldades que algumas pessoas têm ao se trabalhar com o modelo colaborativo do git, é manter seu repositório atualizado com o repositório oficial.
Quando realizamos um clone de um repositório fork, para o git aquele repositório é o principal. Mas no modelo colaborativo, é necessário configurar o git para reconhecer o repositório oficial também. Isso nos ajudará a manter o repositório atualizado com o oficial.
Para isso vamos configurar "os Remotes" do git.
Vá no menu "Git" -> "Manage Remotes"
Irá aparecer uma janela para configurar os remotes. Note que já temos dois remotes configurados, um para o Core e outro para o Datapack. O remote do core está correto, mas o Datapack está configurado para o repositório oficial. Isso ocorre devido ao arquivo de configuração responsável pelo submodule.
Vamos corrigir o Datapack e adicionar mais dois remotes. Para isso vamos pegar a url dos repositórios oficiais. Após a configuração os remotes ficaram assim:
Após a configuração, vamos atualizar o repositório com o conteúdo dos novos remotes, para isso vá no menu "Git" -> Fetch.
Vamos acessar a tab git do IntelliJ, por padrão fica no canto inferior esquerdo, para vermos com mais detalhes o conteúdo do repositório. Aqui podemos ver os conteúdo tanto do repositório fork quanto do oficial.
4º Passo - Realizando mudanças
Vamos realizar um mudança simples, apenas para demonstrar como o workflow funciona.
A primeira coisa a fazer antes de realizar a mudança é criar uma nova branch.
Clique na branch development, canto inferior direito, depois "New Branch".
Der um nome sugestivo para a branch, de forma a dar uma ideia o que aquela branch vai corrigir ou modificar.
Agora podemos realizar a mudança desejada. Após realizar a mudança, vamos abrir a aba "commit" que fica do lado esquerdo. Nessa janela podemos selecionar quais os arquivos que fazem parte da mudança, para enviar a modificação para o repositório.
Após selecionar os arquivos necessários, preenchemos a mensagem do commit com uma algo que descreva o que está sendo mudado. O ideal é que se utilize poucas palavras para descrever a mudança.
Em casos em que é necessário algo mais detalhado, escreva na primeira uma descrição breve, e após uma linha escreva a descrição completa.
Agora podemos fazer o commit e o push das mudanças.
Commit -> realiza a mudança no seu repositório local
Push -> envia a mudança para o respositório remoto ( github)
Abrirar uma tela para alterar alguma opção do push, se necessário. Aqui podemos ver que será criada uma nova branch no repositório remoto, sinalizado pelo label "new" após o nome da branch. Após verificar que está tudo correto, clique no "push".
*Lembrando que o remote origin é o repositório fork, então a mudança vai para esse repositório e não para o oficial.
Após o push, vamos olhar como ficou o repositório no github.
Podemos ver que ao entrar no github ele já nos mostra que foi realizado um push recentemente no repositório. E finalmente fornece um botão para realizarmos o pull request.
Clique no botão "compare & pull request".
O github abrirá a página de pull request do repositório oficial, automaticamente preencherar algumas informações com a mensagem que colocamos no commit.
Nessa página, podemos configurar para qual branch o pull request será feito. Por padrão ele fará o pull request na branch "development", caso o pull request seja para outra branch você pode alterá-la.
Clique no botão "Create pull request". Ao criar o pull request a mudança vai passar por algumas checagens automáticas, e ficará aberto para alguém da equipe analisar o que foi mudado.
Essa é fase que chamamos de code review, aqui fazemos uma verificação geral da mudança.
Algumas das coisas que verificamos aqui:
A qualidade do código;
Se a mudança faz sentido;
Se a mudança é necessária;
Se o código faz o que supostamente deveria fazer;
Se não existe código malicioso;
entre outras coisas;
Alguma pessoa do time irá realizar o review do código, podendo aprovar, pedir mudanças ou apenas não aceitar o pull request
5º Passo - Atualizando o repositório com o conteúdo do repositório oficial
Após o pull request ser aceito, ele é incorporado ao repositório oficial. Então é necessário que o repositório fork e o local seja sempre atualizado também.
Para isso, vamos voltar ao IntelliJ. A primeira coisa a fazer é retornar para nossa branch padrão "development". Vamos fazer o checkout dela.
Agora vamos fazer o pull (copiar) das alterações realizados no repositório oficial. Você pode clicar com o botão direito em algum arquivo do projeto -> Git -> Pull...
Vamos configurar de onde queremos receber as atualizações, nesse caso queremos atualizar a nossa branch com o repositório oficial e branch development, que foi a que submetemos o pull request.
Podemos ver que nossa branch local está atualizada com a mudança que fizemos no pull request:
Após realizar o pull dessas alterações, você pode fazer push para o seu repositório fork, para mantê-lo sempre atualizado.
Esse processo pode parecer um pouco complicado, ou até mesmo com vários passos. Mas é uma forma de coloboração bastante eficaz que permite a fácil utilização de múltiplos repositórios, sem muitas complicações de merge. Mas isso já é uma outra história.
O importante é sempre lembrar:
Antes de fazer qualquer mudança crie uma nova branch sempre a partir da branch padrão, nesse caso "development"
Se seu pull request não foi aprovado ainda, e você precisa fazer uma alteração diferente, volte para branch padrão, crie uma nova branch apartir dela e só então comece a realizar a próxima mudança
Lembre-se de manter seu repositório sempre atualizado com o oficial
De vez em quando faça uma limpeza, delete as branchs que foram criadas e as mudanças já foram aprovadas. Lembre-se o modelo é "short lived branch" então elas tem vida curta mesmo.
[]'s
12_56.50-Copia.thumb.jpg.4562334d007255db00ccc774e0e0448d.jpg)