Contribuindo com um projeto

Contribuir com um projeto no GitHub é uma habilidade essencial para desenvolvedores e colaboradores que trabalham juntos para alcançar metas compartilhadas. Quer você esteja corrigindo bugs, adicionando recursos ou aprimorando a documentação, o processo de contribuição garante a colaboração estruturada e eficiente.

Ao seguir o fluxo do GitHub de fazer fork de repositórios, criar branches e enviar pull requests, você pode propor alterações em um projeto e obter feedback sem interromper o trabalho de outras pessoas.

Este guia fornece instruções sobre como contribuir para um projeto usando a interface do usuário do GitHub e a linha de comando. Para obter mais informações sobre como contribuir com GitHub Desktop, consulte Clonagem e bifurcar repositórios do GitHub Desktop. Para obter o mesmo com GitHub CLI (Interface de Linha de Comando), consulte Início rápido da CLI GitHub.

Sobre a bifurcação

Se você quiser contribuir com o projeto de outra pessoa, mas não tiver permissão para fazer alterações diretamente, poderá criar sua cópia do projeto, fazer atualizações e sugerir essas atualizações para inclusão no projeto principal. Este processo é frequentemente chamado de fluxo de trabalho "fork e pull request".

Quando você cria sua cópia (ou "fork") de um projeto, é como criar um workspace que compartilha código com o projeto original. Isso é útil para projetos de código aberto ou quando você não tem permissão de escrita no projeto original.

Depois de fazer alterações em sua cópia, você pode enviá-las como uma pull request, que é uma maneira de propor alterações de volta ao projeto principal. Para saber mais, confira Fazer um fork de um repositório.

Criando sua cópia de um projeto

Este tutorial usa o projeto Spoon-Knife, um repositório de teste hospedado no GitHub que permite testar o fluxo de trabalho da pull request e do fork.

1. Navegue até o projeto Spoon-Knife em https://github.com/octocat/Spoon-Knife.

2. No canto superior direito da página, clique em Fork.

   

3. Em "Proprietário", selecione o menu suspenso e clique em um proprietário do repositório com fork.

   Observação

   Se o nome de usuário estiver esmaecido, o fork já existe. Em vez disso, você deve atualizar o fork existente. Para saber mais, confira Sincronizar uma bifurcação.

4. Por padrão, os forks são nomeados da mesma forma que os repositórios upstream. Opcionalmente, para destacar ainda mais seu fork, no campo "Nome do repositório", digite um nome.

5. Opcionalmente, no campo "Descrição", digite uma descrição do fork.

6. Se desejar, selecione Copiar somente o branch PADRÃO.

   Em muitos cenários de bifurcação, como contribuir para projetos de código aberto, você só precisa copiar o ramo padrão. Se você não selecionar essa opção, todos os branches serão copiados para o novo fork.

7. Clique em Criar bifurcação.

Clonando um fork para o seu computador

Você fez um fork do repositório Spoon-Knife com sucesso, mas ele só existe no GitHub por enquanto. Para poder trabalhar no projeto, você deverá cloná-lo para o seu computador.

Você pode clonar o seu fork com a interface de linha de comando, GitHub CLI ou GitHub Desktop.

1. No GitHub, acesse seu fork do repositório Spoon-Knife.

2. No Mac ou Linux, abra o Terminal. No Windows, abra o Git Bash.

3. Altere o diretório de trabalho atual para o local em que deseja ter o diretório clonado.

4. Escreva git clonee, em seguida, cole o URL que copiou anteriormente. Terá este formato, com seu nome de usuário do GitHub em vez de YOUR-USERNAME:

   git clone https://github.com/YOUR-USERNAME/Spoon-Knife
   

5. Pressione Enter. Seu clone local será criado.

   $ git clone https://github.com/YOUR-USERNAME/Spoon-Knife
   > Cloning into `Spoon-Knife`...
   > remote: Counting objects: 10, done.
   > remote: Compressing objects: 100% (8/8), done.
   > remove: Total 10 (delta 1), reused 10 (delta 1)
   > Unpacking objects: 100% (10/10), done.
   

Como criar um branch de trabalho

Antes de fazer alterações no projeto, você deve criar um novo branch e fazer o checkout dele. Ao manter as alterações em seu próprio branch, você segue o fluxo de GitHub e garante que será mais fácil contribuir para o mesmo projeto novamente no futuro. Confira fluxo de GitHub.

git branch BRANCH-NAME
git checkout BRANCH-NAME

Fazendo e enviando por push as alterações

Vá em frente e faça algumas alterações no projeto usando seu editor de texto favorito, como o Visual Studio Code. Você pode, por exemplo, alterar o texto em index.html para adicionar seu nome de usuário do GitHub.

Quando estiver pronto para enviar suas alterações, teste e faça commit das suas alterações. git add . informa o Git de que você deseja incluir todas as alterações no próximo commit. git commit cria um instantâneo dessas alterações.

git add .
git commit -m "a short description of the change"

Ao preparar e confirmar arquivos, você essencialmente diz ao Git: "Tire um snapshot das minhas alterações". Você pode continuar fazendo mais alterações e tirando mais snapshots de commit.

No momento, suas alterações existem apenas localmente. Quando estiver pronto para enviar suas alterações para GitHub, envie suas alterações para o repositório remoto.

git push

Fazendo um pull request

Criar uma pull request é a última etapa para produzir um fork do projeto de outra pessoa. Quando você faz uma alteração benéfica e deseja propor isso ao repositório original, você cria um pull request para um mantenedor revisar.

Para fazer isso, navegue até o repositório no GitHub em que o projeto está. Neste exemplo, ele estará em https://github.com/<your_username>/Spoon-Knife. Você verá um banner indicando que seu branch está um commit à frente de octocat:main. Clique em Contribuir e em Abrir uma solicitação de pull.

O GitHub levará você a uma página que mostra as diferenças entre seu fork e o repositório octocat/Spoon-Knife. Clique em Criar solicitação de pull.

O GitHub levará você a uma página para inserir um título e uma descrição das alterações. É importante fornecer o máximo de informações úteis e uma justificativa para por que você está fazendo este pull request em primeiro lugar. O proprietário do projeto deve poder determinar se a sua alteração é tão útil para todos quanto você pensa. Por fim, clique em Criar solicitação de pull.