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.

Seguindo o fluxo do GitHub de criar forks de repositórios, criar branches e enviar pull requests, você pode propor alterações em um projeto e obter comentários sem interromper o trabalho de outras pessoas.

Este guia fornece instruções sobre como contribuir para um projeto usando a interface do usuário e a linha de comando do GitHub. Para obter mais informações sobre como contribuir com o GitHub Desktop, consulte Clonagem e bifurcar repositórios do GitHub Desktop. Para fazer o mesmo com a CLI (Interface de Linha de Comando) do GitHub, consulte Início rápido da CLI do 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. Esse processo costuma ser chamado de fluxo de trabalho de "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 software livre ou sempre que você não tem acesso de gravação ao 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 Criar 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 Criar 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 respectivos repositórios pai. Opcionalmente, para distinguir ainda mais o fork, no campo "Nome do repositório", digite um nome.

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

6. Opcionalmente, selecione Copiar somente o branch PADRÃO.

   Para muitos cenários de bifurcação, como contribuir para projetos de código aberto, você só precisa copiar o branch 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 seu computador

Você criou um fork no repositório Spoon-Knife, mas ele só existe no GitHub até agora. Para poder trabalhar no projeto, você deverá cloná-lo para o seu computador.

Você pode clonar a sua bifurcação com a linha de comando, GitHub CLI ou GitHub Desktop.

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

2. Acima da lista de arquivos, clique em Code.

   

3. Copie a URL do repositório.

   • Para clonar o repositório usando HTTPS, em "HTTPS", clique em .

   • Para clonar o repositório usando uma chave SSH, incluindo um certificado emitido pela autoridade de certificação SSH da sua organização, clique em SSH e em .

   • Para clonar um repositório usando a GitHub CLI, clique em GitHub CLI e em .

     

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

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

6. Digite git clone e cole a URL já copiada. Ela terá esta aparência, com seu nome de usuário do GitHub em vez de YOUR-USERNAME:

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

7. Pressione Enter. Seu clone local estará 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ê precisa criar um branch e fazer check-out dele. Mantendo as alterações em seu branch, você segue o fluxo do GitHub e garante que será mais fácil contribuir com o mesmo projeto novamente no futuro. Confira Fluxo do 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 testar e fazer commit dos arquivos, você essencialmente diz ao Git, "Faça um instantâneo das minhas alterações". Você pode continuar fazendo mais alterações e tirar mais instantâneos do commit.

No momento, suas alterações existem apenas localmente. Quando estiver com tudo pronto para enviar alterações por push ao GitHub, envie-as para o 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á uma notificação indicando que o 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 tantas informações úteis e uma razão para o motivo de você estar fazendo este pull request. 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.

Familiarizando-se com um projeto

Se você é novo em um projeto, pode usar o Copilot para ajudá-lo a entender a finalidade do repositório, examinar arquivos e se aprofundar em linhas de código específicas. Confira Usando o GitHub Copilot para explorar projetos.