Contribuindo com um projeto

Aprenda a contribuir para um projeto por meio da bifurcação.

Platform navigation

Neste artigo

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.

    Captura de tela da página principal de um repositório. Um botão, rotulado com um ícone de fork e "Fork 59.3k", está contornado em laranja escuro.

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

    Note

    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.

Note

Se você quiser copiar branches adicionais do repositório upstream, poderá fazê-lo na página Branches. Para saber mais, confira Criar e excluir branches no repositório.

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 Código.

    Captura de tela da lista de arquivos na página de aterrissagem de um repositório. O botão "Código" está realçado com um contorno laranja escuro.

  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 .

      Captura de tela do menu suspenso "Código". À direita da URL HTTPS do repositório, um ícone de cópia está contornado em laranja escuro.

  4. Abra TerminalTerminalGit 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.

Note

Para saber mais sobre GitHub CLI, confira Sobre o a CLI do GitHub.

Para criar um clone do fork, use o sinalizador --clone.

gh repo fork REPOSITORY --clone=true

  1. No menu Arquivo, clique em Clonar Repositório.

    Captura de tela da barra de menus no Mac. O menu suspenso "Arquivo" é expandido e a opção "Clonar Repositório" está realçada com um contorno laranja.

    Captura de tela da barra de menus "GitHub Desktop" no Windows. O menu suspenso "File" é expandido, e a opção "Clone Repository" está contornada em laranja.

  2. Clique na aba que corresponde à localização do repositório que você deseja clonar. Clique também na URL para inserir o local do repositório manualmente.

    Captura de tela da janela "Clonar um repositório". Na parte superior da janela, as guias "GitHub.com", "GitHub Enterprise" e "URL" estão contornadas em laranja.

  3. Na lista de repositórios, clique no repositório que você deseja clonar.

    Captura de tela da janela "Clonar um repositório". O repositório "github/docs" está realçado com um contorno laranja.

  4. Para selecionar o diretório local no qual você deseja clonar o repositório, ao lado do campo "Caminho Local", clique em Escolher... e navegue até o diretório.

    Captura de tela da janela "Clonar um repositório". O botão, rotulado como "Escolher", está realçado com um contorno laranja.

  5. Na parte inferior da janela "Clonar um Repositório", clique em Clonar.

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

git branch BRANCH-NAME
git checkout BRANCH-NAME

Para obter mais informações de como criar e gerenciar branches no GitHub Desktop, confira Gerenciar branches no GitHub Desktop.

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"

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

Para obter mais informações de como preparar e fazer commit nas alterações no GitHub Desktop, confira Fazer commit e revisar as alterações no seu projeto no GitHub Desktop.

Ao testar e fazer commit dos arquivos, você essencialmente diz ao Git, "Ok, tire 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

git push

Para obter mais informações de como efetuar push nas alterações no GitHub Desktop, confira Enviar alterações por push para o GitHub do GitHub Desktop.

Fazendo um pull request

Finalmente, você está pronto para propor alterações no projeto principal! Essa é a última etapa para produzir uma bifurcação do projeto de outra pessoa, e a mais importante, indiscutivelmente. Se você fez uma alteração que você considera que beneficiaria a comunidade como um todo, você deve considerar contribuir de novamente.

Para fazer isso, acesse 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.

Gerenciando feedback

Os pull requests são uma área de discussão. Não se ofenda se o proprietário do projeto rejeitar o seu pull request ou pedir mais informações sobre o motivo da alteração. Mesmo que o proprietário do projeto opte por não mesclar seu pull request, suas alterações ainda existirão no fork. Talvez outra pessoa considere seu fork muito mais valioso do que o projeto original.

Como localizar os projetos

Você fez uma bifurcação com sucesso e contribuiu de volta para um repositório. Vá em frente e contribua um pouco mais! Para obter mais informações, confira Encontrando maneiras de contribuir com o código aberto no GitHub.

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.