Contribuindo com um projeto

Contribuir com um projeto no é 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 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 . Para obter mais informações sobre como contribuir com o Desktop, consulte Clonagem e bifurcar repositórios do Desktop. Para fazer o mesmo com a CLI (Interface de Linha de Comando) do , consulte Início rápido da CLI do .

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.

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

1. Navegue até o projeto Spoon-Knife em https://.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.

Você criou um fork no repositório Spoon-Knife, mas ele só existe no 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, CLI ou Desktop.

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

2. Acima da lista de arquivos, clique em Código.

   

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 CLI, clique em 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 em vez de YOUR-USERNAME:

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

7. Pressione Enter. Seu clone local estará criado.

   $ git clone https://.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.
   

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 e garante que será mais fácil contribuir com o mesmo projeto novamente no futuro. Confira Fluxo do .

git branch BRANCH-NAME
git checkout BRANCH-NAME

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 .

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 , envie-as para o remoto.

git push

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 em que o projeto está. Neste exemplo, ele estará em https://.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 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 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.

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 Copilot para explorar projetos.