Workflow colaborativo

Para trabalhar em vários num repositório, existem dois grandes modelos de colaboração. A escolha depende sobretudo de quem tem o direito de escrever no repositório.

Em empresa, usa-se quase sempre a branch partilhada (vista nas lições 01–03). Para contribuir num projeto open source de que não se é membro, passa-se pelo fork.

Um fork é uma cópia pessoal de um repositório na sua conta GitHub. Tem todos os direitos, sem tocar no original. O clone, por seu lado, descarrega um repositório para a máquina local.

Não confundir:

# 1. Fazer fork via o botão "Fork" no GitHub (ou a CLI)
gh repo fork projet/app --clone

# Equivalente manual depois de um fork:
# 2. Clonar O SEU fork
git clone https://github.com/vous/app.git
cd app

# 3. Verificar o remote
git remote -v
# origin  https://github.com/vous/app.git (fetch/push)

O fork é o seu « caixa de areia »: pode partir tudo sem risco para o projeto original. Quando o trabalho está pronto, uma pull request propõe-o ao maintainer, que decide aceitá-lo.

🔧 Mini-exercício — Com gh, faça fork do repositório projet/app e clone-o na sua máquina num só comando.

Enquanto trabalha, o repositório original evolui. O seu fork não se atualiza sozinho. É preciso acrescentar um remote upstream a apontar para o original e depois obter as alterações com regularidade.

# 1. Declarar o repositório original como 'upstream'
git remote add upstream https://github.com/projet/app.git

# 2. Obter as últimas alterações
git fetch upstream

# 3. Atualizar o main local
git switch main
git merge upstream/main

# 4. Enviar para o próprio fork
git push origin main

Sincronizar cedo e com frequência com upstream evita que o fork « derive » do projeto. Quanto mais esperar, mais conflitos haverá no dia da PR.

🔧 Mini-exercício — Escreva o comando para declarar o repositório original https://github.com/projet/app.git como remote upstream.

Uma issue é um ticket: um sítio para assinalar um bug, propor uma funcionalidade ou fazer uma pergunta. É o sistema de acompanhamento de um projeto GitHub.

O que se põe numa boa issue de bug:

# Criar uma issue a partir do terminal
gh issue create --title "Crash ao clicar em Exportar" \
  --body "Etapas: 1) abrir X 2) clicar Exportar → a app fecha-se."

# Listar as issues abertas
gh issue list

# Ligar uma PR a uma issue: na descrição da PR
#   Closes #42   → fecha automaticamente a issue #42 na fusão

Os labels organizam as issues: bug, enhancement, documentation, good first issue, help wanted…

As issues transformam o « era preciso corrigir isto um dia » em tarefas rastreáveis e discutíveis. Ligar uma PR com Closes #N fecha a issue automaticamente na fusão: zero esquecimentos.

🔧 Mini-exercício — Com gh, crie uma issue intitulada « Crash ao clicar em Exportar ».

Para além dos comandos, colaborar com eficácia assenta em convenções partilhadas. Eis as que fazem a diferença.

O padrão dos « Conventional Commits », muito difundido:

git commit -m "feat: adiciona a exportação CSV"
git commit -m "fix: corrige o crash no início de sessão"
git commit -m "docs: atualização do README"
git commit -m "refactor: simplifica o serviço de pagamento"

Uma equipa que partilha convenções não precisa de se concertar sem cessar: o código, os commits e as branches « falam » a mesma língua. É isso, a fluidez colaborativa.

🔧 Mini-exercício — Acabou de adicionar a exportação CSV. Escreva a mensagem de commit no formato Conventional Commits.

Question 1

O que é um fork?

a) Uma fusão de duas branches

b) Uma cópia pessoal de um repositório na sua conta GitHub

c) Um tipo de conflito

d) Uma eliminação do histórico

Question 2

Qual é a diferença entre origin e upstream no modelo fork & pull?

a) Nenhuma, são sinónimos

b) origin é o seu fork, upstream é o repositório original

c) origin é local, upstream está no seu disco

d) upstream serve para apagar branches

Question 3

Para que serve uma issue?

a) Para compilar o código

b) Para assinalar um bug, propor uma funcionalidade ou discutir uma tarefa

c) Para fundir automaticamente as branches

d) Para clonar um repositório

Question 4

O que faz Closes #42 na descrição de uma pull request?

a) Apaga o commit 42

b) Fecha automaticamente a issue #42 quando a PR é fundida

c) Abre uma nova issue

d) Anula a PR

Question 5

O que significa o prefixo de commit fix: nos Conventional Commits?

a) Uma nova funcionalidade

b) Uma correção de bug

c) Documentação

d) Um teste

Instrução

Quer contribuir num projeto open source projet/app de que não é membro. Realize o ciclo completo do modelo fork & pull:

1. Faça fork e clone o repositório.
2. Acrescente o remote upstream e sincronize o seu main.
3. Crie uma branch, faça um commit (a corrigir a issue #8) e envie-a para o seu fork.
4. Abra uma pull request para o repositório original ligando a issue.

Correção

# 1. Fazer fork + clonar
gh repo fork projet/app --clone
cd app

# 2. Acrescentar upstream e sincronizar
git remote add upstream https://github.com/projet/app.git
git fetch upstream
git switch main
git merge upstream/main
git push origin main

# 3. Criar branch, fazer commit, enviar
git switch -c fix/correction-typo-readme
# ... correção do ficheiro README ...
git commit -am "fix: corrige um erro no README"
git push -u origin fix/correction-typo-readme

# 4. Abrir a PR para o repositório ORIGINAL
gh pr create --repo projet/app \
  --base main --head vous:fix/correction-typo-readme \
  --title "fix: erro de digitação no README" \
  --body "Corrige um lapso. Closes #8"

Resultado esperado:

$ git remote -v
origin    https://github.com/vous/app.git (push)
upstream  https://github.com/projet/app.git (fetch)

A PR parte da sua branch (vous:fix/...) para o main do repositório original. O maintainer relê e decide fundir: acaba de contribuir no open source sem nunca ter tido direito de escrita no projeto.

Pontos a reter

1. Dois modelos: branch partilhada (equipa interna) e fork & pull (open source).
2. Fork = cópia na sua conta; clone = cópia na sua máquina.
3. origin = o seu fork; upstream = o repositório original a sincronizar com regularidade.
4. As issues rastreiam bugs, ideias e tarefas; Closes #N liga e fecha na fusão.
5. Boas práticas: commits claros, branches curtas, PR pequenas, main estável.
6. Conventional Commits (feat:, fix:, docs:…) padronizam as mensagens.

A continuação

Este módulo 02 está concluído: já sabe ramificar, fundir, abrir pull requests e colaborar em grande escala. O módulo 03 continua o percurso DevOps com a integração contínua (CI/CD), que automatizará testes e implantações a partir destas mesmas pull requests.