Como contribuir com um repositório no GitHub
Plataforma de hospedagem de código e controle de versão permite que desenvolvedores colaborem em projetos diversos.
O GitHub é uma plataforma de hospedagem de código e controle de versão que permite aos desenvolvedores colaborar em projetos de forma eficiente. Independentemente de você ser o proprietário de um repositório ou um contribuidor, é essencial seguir um processo para manter seu trabalho atualizado e sincronizado com o ramo principal.
Este guia apresenta as etapas necessárias para realizar essas ações usando comandos Git, uma das ferramentas mais populares para gerenciamento de versionamento de código.
No texto abaixo, vou usar muitos termos em Inglês como branch, fork e pull request, mas tentarei traduzi-los onde for possível. São termos comuns para quem trabalha com Git e eu recomendo que você se acostume com eles e aprenda o que cada um significa, caso não fale Inglês.
Como proprietário
Como proprietário de um repositório, você tem controle total sobre o projeto e pode gerenciar o acesso e as permissões de outros contribuidores. Você também pode criar ramos (branches), mesclar solicitações de pull e enviar alterações para o ramo principal. Aqui estão as etapas que você precisa seguir como proprietário:
Etapa 1: Fazer um Fork do Repositório
O forking de um repositório significa criar uma cópia paralela dele em sua conta do GitHub. Isso permite fazer alterações no projeto sem afetar a fonte original. Para fazer um fork de um repositório, vá até sua página no GitHub e clique no botão Fork no canto superior direito. Você verá uma mensagem informando que o repositório está sendo bifurcado. Quando estiver concluído, você terá sua própria cópia do repositório em sua conta.
Etapa 2: Clonar o Repositório
Clonar um repositório significa baixá-lo para sua máquina local para que você possa trabalhar nele offline. Para clonar um repositório, você precisa usar o comando git clone seguido da URL do repositório. Você pode encontrar a URL clicando no botão Code (e na aba Local) na página do seu repositório bifurcado e copiando o link HTTPS. Deve ficar assim no terminal:
git clone https://github.com/jekyll/jekyll.git
Isso criará uma pasta com o mesmo nome do final do endereço do projeto que você está tentando clonar. Neste caso, a pasta jekyll será criada no seu diretório atual com todos os arquivos e pastas do repositório do GitHub.
Etapa 3: Criar um Branch
Um ramo (branch) é uma versão separada do repositório que permite trabalhar em diferentes recursos ou correções de bugs sem afetar o ramo principal. Para criar um ramo, você precisa usar o comando git branch seguido pelo nome do ramo. Por exemplo:
git branch novo-recurso
Isso criará um novo ramo chamado novo-recurso, mas não acessará ele. Para acessar o novo ramo, você precisa usar o comando git checkout seguido pelo nome do ramo. Por exemplo:
git checkout novo-recurso
Isso acessará o ramo novo-recurso e atualizará seu diretório de trabalho.
Etapa 4: Verificar seu status
Para ver quais arquivos foram alterados ou adicionados em seu diretório de trabalho, você pode usar o comando git status. Isso mostrará quais arquivos estão preparados (prontos para serem confirmados), modificados (alterados, mas não preparados) ou não rastreados (novos arquivos que não são rastreados pelo Git). Por exemplo:
git status
Isso mostrará algo como:
On branch novo-recurso
Changes not staged for commit:
(use "git add <file>..." to update what will be committed)
(use "git restore <file>..." to discard changes in working directory)
modified: README.md
Untracked files:
(use "git add <file>..." to include in what will be committed)
novo-arquivo.txt
no changes added to commit (use "git add" and/or "git commit -a")
Passo 5: Adicione suas alterações
Para adicionar suas alterações para serem enviadas, você precisa usar o comando git add seguido do nome do arquivo ou pasta. Por exemplo:
git add README.md
Isso adicionará o arquivo modificado README.md na área de preparação. Você também pode usar . (ponto) como atalho para adicionar todos os arquivos no seu diretório de trabalho. Por exemplo:
git add .
Isso adicionará todos os arquivos modificados e não rastreados na área de preparação.
Passo 6: Faça o commit das suas alterações
Para salvar suas alterações no repositório local, você precisa usar o comando git commit seguido de uma mensagem que descreva o que você fez. Por exemplo:
git commit -m "Novo recurso adicionado"
Isso criará um novo commit com uma descrição “Novo recurso adicionado” e incluirá todos os arquivos que estão na área de preparação.
Passo 7: Envie suas mudanças
Para enviar suas mudanças para o seu repositório remoto no GitHub, você precisa usar o comando git push seguido pelo nome do seu ramo. Por exemplo:
git push origin novo-recurso
Isso enviará seu ramo novo-recurso para o seu repositório bifurcado no GitHub. Você também pode usar -u (upstream) como atalho para definir o ramo remoto como padrão para o seu ramo local. Por exemplo:
git push -u origin novo-recurso
Isso enviará seu ramo novo-recurso e o definirá para rastrear o ramo remoto.
Passo 8: Pull Request
Um pull request é uma maneira de solicitar ao proprietário do repositório original que revise e integre suas alterações ao ramo principal. Para criar um pull request, você precisa ir para a página do seu repositório bifurcado no GitHub e clicar no botão Pull request, no canto superior direito. Você verá uma página onde poderá comparar seu ramo com o ramo principal e escrever um título e uma descrição para sua solicitação de pull.
Assim que terminar, clique no botão Create pull request. Isso enviará uma notificação para o proprietário do repositório original, e eles podem revisar suas alterações e decidir se as aceitam ou não.
Como contribuidor
Como contribuidor, você pode ajudar a melhorar um projeto existente adicionando novos recursos, corrigindo bugs ou melhorando a documentação. Você também pode aprender com outros desenvolvedores e obter feedback sobre o seu trabalho. Aqui estão os passos que você precisa seguir como um contribuidor:
Unsplash/caleb_white
*
Passo 1: Fazer um Fork do Repositório
Assim como proprietários, você também precisa fazer um fork (bifurcar) do repositório ao qual deseja contribuir. Isso criará uma cópia paralela dele em sua conta do GitHub e permitirá que você faça alterações sem afetar a fonte original. Para fazer um fork de um repositório, vá para sua página no GitHub e clique no botão Fork no canto superior direito.
Passo 2: Clonar o Repositório
Após fazer o fork do repositório, você precisa cloná-lo em sua máquina local para que possa trabalhar nele offline. Para clonar um repositório, você precisa usar o comando git clone seguido pela URL do seu repositório bifurcado. Você pode encontrar a URL clicando no botão Code (depois, na aba Local) na página do seu repositório forkado e copiando o link HTTPS. Deve ficar assim
git clone https://github.com/pop-os/pop.git
Passo 3: Adicionar um Link de Upstream
Um link de upstream é uma maneira de conectar seu repositório bifurcado com o repositório original. Isso ajudará você a manter seu repositório bifurcado atualizado, puxando do upstream (a fonte original). Para adicionar um link de upstream, você precisa usar o comando git remote add seguido de um nome (geralmente upstream) e a URL do repositório original. Por exemplo:
git remote add upstream https://github.com/pop-os/pop.git
Isso adicionará um link de upstream chamado upstream que aponta para o repositório original.
Passo 4: Mantenha seu Repositório Fork Atualizado
Antes de começar a trabalhar em quaisquer mudanças, é necessário garantir que o seu repositório fork esteja atualizado com o repositório original. Isso também evitará quaisquer conflitos de merge (mesclar) ao submeter novas mudanças. Para manter seu repositório bifurcado atualizado, é necessário utilizar o comando git pull seguido do nome do link de upstream e o nome do ramo principal. Por exemplo:
git pull upstream main
Isso irá buscar e mesclar quaisquer mudanças do ramo principal do repositório original no seu ramo local.
Passo 5: Crie um Branch
Antes de começar a trabalhar em quaisquer mudanças, é necessário criar um ramo (branch) para cada recurso ou correção de bug que você deseja contribuir. Um ramo é uma versão separada do repositório que permite isolar seu trabalho do ramo principal. Para criar um ramo, é necessário utilizar o comando git branch seguido do nome do ramo. Por exemplo:
git branch novo-recurso
Isso criará um novo ramo chamado novo-recurso, mas não irá acessá-lo. Para acessar um ramo, é necessário utilizar o comando git checkout seguido do nome do ramo. Por exemplo:
git checkout novo-recurso
Isso irá alternar para o ramo novo-recurso e atualizar o seu diretório de trabalho. Também é possível utilizar -b (ramo) como um atalho para criar e alternar para um novo ramo em um único comando. Por exemplo:
git checkout -b novo-recurso
Isso irá criar e acessar o novo ramo novo-recurso ao mesmo tempo.
Passo 6: Verifique seu status
Após criar um ramo e fazer algumas alterações nos arquivos ou pastas no seu diretório de trabalho, você precisa verificar o status usando o comando git status. Isso mostrará quais arquivos estão preparados (staged), modificados ou não rastreados (untracked). Por exemplo:
git status
Isso mostrará algo assim:
On branch novo-recurso
Changes not staged for commit:
(use "git add <file>..." to update what will be committed)
(use "git restore <file>..." to discard changes in working directory)
modified: README.md
Untracked files:
(use "git add <file>..." to include in what will be committed)
novo-arquivo.txt
no changes added to commit (use "git add" and/or "git commit -a")
Passo 7: Adicione suas alterações
Para preparar suas mudanças para confirmação, você precisa usar o comando git add seguido pelo nome do arquivo ou pasta. Por exemplo:
git add README.md
Isso adicionará o arquivo modificado README.md à área de preparação (staging area). Você também pode usar . (ponto) como atalho para adicionar todos os arquivos em seu diretório de trabalho. Por exemplo:
git add .
Isso adicionará todos os arquivos modificados e não rastreados à área de preparação (staging area).
Passo 8: Faça o commit das suas alterações
Para salvar suas mudanças em seu repositório local, você precisa usar o comando git commit seguido de uma mensagem que descreva o que você fez. Por exemplo:
git commit -m "Novo recurso adicionado"
Isso criará um novo commit com a descrição “Novo recurso adicionado” e incluirá todos os arquivos preparados (staged) nele. Você também pode omitir a opção -m e escrever uma mensagem mais detalhada em um editor que será aberto após executar o comando. Por exemplo:
git commit
Isso abrirá um editor onde você pode escrever uma mensagem mais detalhada para o seu commit.
Passo 9: Enviar suas alterações
Para enviar suas alterações para o seu repositório remoto no GitHub, você precisa usar o comando git push seguido do nome do seu ramo. Por exemplo:
git push origin novo-recurso
Isso enviará seu ramo novo-recurso para o seu repositório bifurcado no GitHub.
Passo 10: Pull Request
Para solicitar ao proprietário do repositório original que revise e integre suas alterações no ramo (branch) principal, você precisa criar um pull request no GitHub. Para fazer isso, vá para a página do seu repositório fork no GitHub e clique no botão Pull request, no canto superior direito. Você verá uma página onde pode comparar seu ramo com o ramo principal e escrever um título e uma descrição para sua solicitação.
Quando terminar, clique no botão Create pull request. Isso enviará uma notificação ao proprietário do repositório original e ele poderá revisar suas alterações e decidir se as aceita ou não.
Pronto! Você contribuiu com sucesso para um repositório do GitHub.