LogoLogo
  • Git e GitHub para Humanos
  • Sumário
  • 1. Antes de Começar
    • 1.1 Este Livro é para Você?
    • 1.2 A Razão por Trás Deste Livro
    • 1.3 Visão Geral
    • 1.4 Sobre o GitHub
    • 1.5 Sobre a Cumbuca Dev
    • 1.6 O Maravilhoso Mundo do Open Source
    • 1.7 Mapa do Livro
    • 1.8 Glossário: Capítulo 1
  • 2. Fundamentos de Controle de Versão e Git
    • 2.1 Introdução a Sistemas de Controle de Versão
      • 2.1.1 Sistemas de Controle de Versão Centralizados
      • 2.1.2 Sistemas de Controle de Versão Distribuídos
    • 2.2 Introdução ao Git
    • 2.3 Conceitos Fundamentais do Git
      • 2.3.1 Repositório
      • 2.3.2 Commit
      • 2.3.3 Branch
      • 2.3.4 Merge
    • 2.4 Instalando o Git
      • 2.4.1 Instalando no Linux
      • 2.4.2 Instalando no macOS
      • 2.4.3 Instalando no Windows
    • 2.5 Interagindo com o Git
    • 2.6 O Comando Git
    • 2.7 Inicializando de um Repositório Local
    • 2.8 Configurando de um Repositório Local
    • 2.9 Links Úteis: Capítulo 2
    • 2.10 Glossário: Capítulo 2
  • 3. Operações Locais Básicas no Git
    • 3.1 Explorando Operações Locais do Git
    • 3.2 Salvando Alterações Localmente
      • 3.2.1 Adicionando Arquivos ao Controle de Versão via `git add`
      • 3.2.2 Verificando o Estado do Repositório via `git status`
      • 3.2.3 Criando Commits via `git commit`
      • 3.2.4 Visualizando o Histórico do Repositório via `git log`
      • 3.2.5 Comparando Alterações via `git diff`
      • 3.2.6 Unindo os Pontos
      • 3.2.7 Exemplo Prático
    • 3.3 Trabalhando com Branches Localmente
      • 3.3.1 Gerenciando Branches via `git branch`
      • 3.3.2 Alternando Entre Branches via `git switch`
      • 3.3.3 Mesclando Branches via `git merge`
        • 3.3.3.1 Resolvendo Conflitos de Merge
      • 3.3.4 Unindo os Pontos
      • 3.3.5 Exemplo Prático
    • 3.4 Links Úteis: Capítulo 3
    • 3.5 Glossário: Capítulo 3
  • 4. Ajuste de Mudanças Locais no Git
    • 4.1 Desfazendo Alterações Localmente
      • 4.1.1 Desfazendo Alterações Antes do Commit
      • 4.1.2 Desfazendo Commits
      • 4.1.3 Alterando o Último Commit via `git commit --amend`
      • 4.1.4 Unindo os Pontos
      • 4.1.5 Exemplos Práticos
    • 4.2 Ignorando e Removendo Arquivos do Rastreamento Local
      • 4.2.1 Ignorando Arquivos do Rastreamento Utilizando o arquivo .gitignore
      • 4.2.2 Removendo Arquivos do Rastreamento via `git rm`
    • 4.3 Links Úteis: Capítulo 4
    • 4.4 Glossário: Capítulo 4
  • 5. Introdução ao GitHub
    • 5.1 Qual a diferença entre Git e GitHub?
    • 5.2 Grandes Projetos Abertos no GitHub
    • 5.3 Recursos do GitHub
    • 5.4 Idioma Suportado no GitHub
    • 5.5 Contas no GitHub
      • 5.5.1 Conta Pessoal
      • 5.5.2 Conta de Organização
      • 5.5.3 Conta Corporativa
      • 5.5.4 Unindo os Pontos
    • 5.6 Planos do GitHub
    • 5.7 Criando uma Conta Pessoal no GitHub
    • 5.8 Explorando a Interface do GitHub
      • 5.8.1 Página Principal (Home)
      • 5.8.2 Página de Notificações (Notifications)
      • 5.8.3 Página de Configurações (Settings)
    • 5.9 Links Úteis: Capítulo 5
    • 5.10 Glossário: Capítulo 5
  • 6. Repositórios no GitHub
    • 6.1 O quê é um Repositório no GitHub?
    • 6.2 Criando um Repositório no GitHub
    • 6.3 Página Principal de um Repositório: Aba Code
      • 6.3.1 Editando um Arquivo em um Repositório no GitHub
      • 6.3.2 Explorando o Histórico de Commits de um Repositório no GitHub
      • 6.3.3 Editando Detalhes de um Repositório no GitHub
      • 6.3.4 Explorando um Repositório Ativo em Uso
    • 6.4 Página de Configurações de um Repositório: Aba Settings
      • 6.4.1 Gerenciando Configurações Gerais de um Repositório no GitHub: Menu General
      • 6.4.2 Gerenciando Configurações de Colaboração de um Repositório no GitHub: Menu Collaborators
      • 6.4.3 Explorando Configurações de um Repositório no GitHub na Prática
    • 6.5 Links Úteis: Capítulo 6
    • 6.6 Glossário: Capítulo 6
  • 7. Documentação de Projetos
    • 7.1 O quê é Documentação de Projeto?
    • 7.2 Explorando a Linguagem de Marcação Markdown
    • 7.3 Criando uma Página de Apresentação no GitHub
    • 7.4 Links Úteis: Capítulo 7
    • 7.5 Glossário: Capítulo 7
  • 8. Issues no GitHub
    • 8.1 O quê é GitHub Issues?
    • 8.2 Criando uma Issue no GitHub
    • 8.3 Explorando a Página de uma Issue no GitHub
    • 8.4 Atribuindo uma Issue no GitHub
    • 8.5 Categorizando Issues de um Repositório através de Labels no GitHub
      • 8.5.1 Gerenciando Labels de um Repositório no GitHub
    • 8.6 Página de Issues de um Repositório no GitHub: Aba Issues
    • 8.7 Explorando Issues no Mundo Real
    • 8.8 Links Úteis: Capítulo 8
    • 8.9 Glossário: Capítulo 8
  • 9. Git Remoto
    • 9.1 Explorando Operações Remotas do Git
    • 9.2 Interagindo com o Repositório Remoto Central no Git
      • 9.2.1 Clonando um Repositório Remoto via `git clone`
      • 9.2.2 Buscar Atualizações de um Repositório Remoto via `git fetch`
      • 9.2.3 Enviando Mudanças Locais para o Repositório Remoto via `git push`
      • 9.2.4 Sincronizando o Repositório Local com o Remoto via `git pull`
      • 9.2.5 Unindo os Pontos
      • 9.2.6 Exemplo
    • 9.3 Interagindo com o Repositório Remoto hello-world
      • 9.3.1 Conectando-se ao GitHub via SSH
      • 9.3.2 Clonando o Repositório hello-world
      • 9.3.3 Alterando hello-world Localmente
        • 9.3.3.1 Editor de Código
        • 9.3.3.2 Editando README.md
        • 9.3.3.3 Salvando Alterações no Controle de Versão Local
      • 9.3.4 Enviando Alterações para o Repositório Remoto
    • 9.4 Links Úteis: Capítulo 9
    • 9.5 Glossário: Capítulo 9
  • 10. Pull Requests no GitHub
    • 10.1 O quê é um Pull Requests no GitHub?
    • 10.2 Entendendo as Propriedades de um Pull Request no GitHub
      • 10.2.1 Branches de Origem e de Destino de um Pull Request
      • 10.2.2 Título de um Pull Request
      • 10.2.3 Descrição de um Pull Request
      • 10.2.4 Modificações de um Pull Request
      • 10.2.5 Pessoas Revisoras de um Pull Request
      • 10.2.6 Labels de um Pull Request
    • 10.3 Criando um Pull Request no GitHub
    • 10.4 Página de um Pull Request no GitHub
      • 10.4.1 Aba Conversation
      • 10.4.2 Aba Commits
      • 10.4.3 Aba Checks
      • 10.4.4 Aba Files Changed
    • 10.5 Página de Pull Requests de um Repositório no GitHub: Aba Pull Requests
    • 10.6 Recebendo Revisões em um Pull Request no GitHub
      • 10.6.1 Boas Práticas
      • 10.6.2 Exemplo Prático
        • 10.6.2.1 Adicionando Conta Colaboradora
        • 10.6.2.2 Solicitando Revisão de Pull Request
        • 10.6.2.3 Lidando com o Feedback
    • 10.7 Mesclando um Pull Request no GitHub
      • 10.7.1 Exemplo Prático
    • 10.8 Atualizando um Repositório Local Após Mesclagem
    • 10.9 Explorando Pull Requests no Mundo Real
    • 10.10 Links Úteis: Capítulo 10
    • 10.11 Glossário: Capítulo 10
  • 11. Fluxo de Trabalho
    • 11.1 Fork no GitHub
      • Fork
    • 11.2 Forks e Pull Requests
      • 11.2.1 Criando um Fork no GitHub
      • 11.2.2 Clonando um Fork
      • 11.2.3 Realizando Alterações Localmente
      • 11.2.4 Enviando Alterações Locais para o Fork Remoto
      • 11.2.5 Criando um Pull Request a partir de um Fork no GitHub
      • 11.2.6 Sincronizando um Fork no GitHub
      • 11.2.7 Revisão, Mesclagem e Atualizações Pós-mesclagem
    • 11.3 Fluxo de Trabalho
  • 11.4 Links Úteis - Capítulo 11
  • 11.5 Glossário - Capítulo 11
  • 12. O Caminho Continua
    • 12.1 Conhecendo Ferramentas Adicionais
      • 12.1.1 Indicação: Jogo Oh My Git
    • 12.2 Explorando Projetos Open Source
    • 12.3 Crescendo e Colaborando em Comunidades
    • 12.4 Desafio: GitCaos 🔥
    • 12.5 Links Úteis - Capítulo 12
    • 12.6 Glossário Completo: Git e GitHub para Humanos
Fornecido por GitBook
Nesta página
  • Boas Práticas
  • 1. Descreva o Problema e a Solução
  • 2. Objetividade, mas com Completude
  • 3. Explique a Motivação da Mudança
  • 4. Adicione Capturas de Telas ou GIFs
  • 5. Explique Decisões Importantes
  • 6. Siga o Padrão do Repositório
  • 7. Use Palavras-chave para Fechar Issues
  • 8. Utilize Markdown
  • Exemplos de Boas Descrições ✅
  • Contra-exemplos ❌

Isto foi útil?

Editar no GitHub
Exportar como PDF
  1. 10. Pull Requests no GitHub
  2. 10.2 Entendendo as Propriedades de um Pull Request no GitHub

10.2.3 Descrição de um Pull Request

A descrição do Pull Request (PR) é um espaço para explicar em detalhes as mudanças feitas no código. Assim como a descrição de uma Issue, ela ajuda a equipe a entender o contexto da alteração, os problemas resolvidos e os impactos que podem ocorrer. Uma boa descrição facilita a revisão, melhora a colaboração e documenta as mudanças para o futuro.

Boas Práticas

1. Descreva o Problema e a Solução

Explique qual era o problema e como foi resolvido. Dê contexto suficiente para que quem revisa não precise adivinhar o que motivou a mudança. Se houver contexto adicional, como discussões prévias ou decisões do time, inclua essas informações.

2. Objetividade, mas com Completude

Dê informações suficientes para a revisão sem entrar em detalhes desnecessários. Seja claro sobre o que mudou e por quê.

3. Explique a Motivação da Mudança

Além de descrever o que foi feito, é importante explicar por que a alteração foi necessária. Isso ajuda a equipe a entender o contexto e a tomar decisões melhores no futuro. Se a mudança resolve um problema específico ou melhora um fluxo, deixe isso claro na descrição.

4. Adicione Capturas de Telas ou GIFs

Se a alteração impacta a interface gráfica ou muda fluxos visuais, adicionar imagens ou GIFs pode facilitar a revisão.

5. Explique Decisões Importantes

Se alguma escolha no código não estiver óbvia, comente na descrição para ajudar quem está revisando.

6. Siga o Padrão do Repositório

Assim como para o título do PR, é essencial seguir as diretrizes do repositório para garantir que sua contribuição seja bem recebida. Isso facilita a revisão e mantém a consistência do projeto. Antes de abrir um PR:

  • Verifique se há um arquivo CONTRIBUTING.md, que pode conter instruções específicas.

  • Observe PRs já abertos para entender como as descrições são estruturadas.

  • Caso exista um template de PR, preencha todas as informações solicitadas e siga o formato indicado.

Manter um padrão no projeto agiliza a revisão, melhora a colaboração e torna o histórico de mudanças mais organizado.

7. Use Palavras-chave para Fechar Issues

Ao criar um PR que resolve uma Issue, você pode usar palavras-chave para referenciá-la automaticamente. O GitHub fechará automaticamente a Issue quando o PR for mesclado. As palavras-chave disponíveis são:

  • Fixes #123 (Corrige a Issue #123)

  • Closes #456 (Encerra a Issue #456)

  • Resolves #789 (Resolve a Issue #789)

Qualquer uma dessas palavras pode ser utilizada para referenciar e fechar a Issue correspondente. Mais detalhes podem ser encontrados na documentação oficial do GitHub.

8. Utilize Markdown

O Markdown facilita a visualização e organização das informações na descrição do PR, tornando o conteúdo mais legível. Assim como nas Issues, a descrição do PR aceita Markdown para formatação, e é possível visualizar o preview antes de enviar.

Exemplos de Boas Descrições ✅

Exemplo 1: Correção de bug

# Corrige erro de cálculo no carrinho de compras

**Problema**: O cálculo de desconto estava incorreto para pedidos acima de R$ 100,00.
**Solução**: Ajustado o cálculo da função calcular_desconto().
**Testes**: Adicionados novos testes unitários para garantir a precisão do cálculo.
**Issue relacionada**: Fixes #123.

Exemplo 2: Nova funcionalidade

# Permitir exclusão de pedidos na página de pedidos

## O que foi feito?
- Adicionado um botão "Excluir" na página de pedidos.
- Implementado um alerta de confirmação para evitar exclusões acidentais.
- Atualizada a documentação para incluir essa nova funcionalidade.

## Motivação
Antes, não havia uma forma direta de excluir pedidos, o que exigia 
ações manuais no banco de dados. Agora, essa operação pode ser feita 
com segurança e de forma intuitiva.

## Antes
[gif mostrando que não havia opção para excluir pedidos]

## Depois
[gif mostrando o novo botão e o alerta de confirmação]

Closes #123

Contra-exemplos ❌

  • Deixar a descrição vazia.

  • "Correção de bug" → Qual bug? Onde? Como foi resolvido?

  • "Melhorias no sistema" → Muito genérico.

  • "Novo endpoint" → Qual endpoint? Para quê?

Uma descrição bem feita melhora a colaboração e torna o histórico do projeto mais organizado. Seguir boas práticas faz com que PRs sejam revisados mais rapidamente e evita retrabalho. Sempre siga os padrões do repositório e aproveite os recursos do Markdown para deixar suas descrições mais claras!

Anterior10.2.2 Título de um Pull RequestPróximo10.2.4 Modificações de um Pull Request

Atualizado há 15 dias

Isto foi útil?