Mensagens de commit e changelog simples

Nível: A2

Objetivo

Escrever mensagens de commit curtas no estilo imperativo (Add, Fix, Update, Remove) e redigir release notes simples, distinguindo o imperativo do past simple usado em changelogs narrativos.

Explicação

Em projetos de software, o commit message é a frase curta que descreve uma mudança no código. A convenção mais usada em inglês é o estilo imperativo: o verbo aparece no infinitivo, como se você estivesse dando uma instrução direta ao repositório.

Comece a mensagem com um verbo imperativo comum:

• `Add ...` para uma nova funcionalidade ou arquivo.
• `Fix ...` para corrigir um bug.
• `Update ...` para ajustar uma dependência, texto ou comportamento.
• `Remove ...` para apagar código antigo.
• `Refactor ...` para reorganizar o código sem mudar o comportamento.
• `Improve ...` para uma melhoria pequena em algo que já existe.

Exemplos corretos:

• `Add export button to the dashboard`
• `Fix crash on empty cart`
• `Update API client to v2`
• `Remove deprecated v1 endpoint`

A primeira letra é maiúscula e a linha de assunto não termina com ponto. A frase deve ser curta, com até 50 caracteres quando possível, e descrever o que mudou, não o autor nem o tempo verbal.

`Add export button` está correto. `Added export button`, `I added the export button` ou `Adding export button` não são adequados como mensagem de commit. A forma imperativa é a convenção porque, ao ler o histórico com `git log`, o commit deve soar como uma instrução clara aplicada ao código.

O corpo do commit (opcional) pode ser mais longo. Nele, é comum usar past simple ou present simple para explicar por que a mudança foi necessária: `The dashboard didn't show the total. Added a new button to export the data.` Esse contraste é importante: o assunto fica no imperativo, mas a explicação pode estar no past simple.

O changelog ou release notes tem um estilo diferente. Em vez de uma instrução por commit, é uma lista curta que resume todas as mudanças de uma versão. Existem dois formatos comuns:

1. Imperativo, igual ao commit: `Add export button`, `Fix date format`.
2. Categorizado com cabeçalhos em past simple: `### Added`, `### Fixed`, `### Changed`. Dentro de cada categoria, o bullet pode estar no past simple (`Added export button`) ou no imperativo (`Add export button`), mas o estilo deve ser consistente dentro do mesmo changelog.

Mantenha cada linha do changelog curta, comece cada bullet com a mesma forma verbal e agrupe por categoria para que o leitor encontre rapidamente o que mudou.

Exemplos

Erros comuns

• Usar past simple no assunto do commit: `Added login button` deve ser `Add login button`.
• Colocar pronome antes do verbo: `I added the login button` deve ser `Add login button`.
• Terminar o assunto com ponto: `Add export button.` deve ser `Add export button`.
• Esquecer a maiúscula inicial: `add export button` deve ser `Add export button`.
• Misturar estilos dentro do mesmo changelog: escolha imperativo ou past simple e mantenha o mesmo padrão em todas as linhas.
• Descrever o que você fez em vez do que mudou: prefira `Fix crash on empty cart` em vez de `I changed the cart code`.

Prática guiada

Reescreva estas frases no estilo imperativo correto para uma mensagem de commit:

• `I added a new export button to the dashboard.`

→ `Add export button to the dashboard`

• `We fixed the crash when the cart is empty.`

→ `Fix crash on empty cart`

• `I updated the API client to v2.`

→ `Update API client to v2`

• `They removed the old v1 endpoint.`

→ `Remove deprecated v1 endpoint`

Observe quatro pontos:

1. O verbo perde o `-ed` e o `-s` e volta ao infinitivo.
2. O pronome (`I`, `we`, `they`) desaparece.
3. A frase continua começando com letra maiúscula.
4. O ponto final do assunto é removido.

Agora monte um changelog de três linhas para uma versão 1.4 com as mudanças acima. Use `### Added`, `### Fixed` e `### Changed` como cabeçalhos, escolha um único estilo (imperativo ou past simple) e mantenha-o nas três linhas.

Resumo

Mensagens de commit usam o estilo imperativo (Add, Fix, Update, Remove) no assunto, sem pronome, sem -ed e sem ponto final. O corpo do commit pode usar past simple para explicar o porquê. O changelog lista as mudanças da versão, geralmente agrupadas em Added, Fixed e Changed, com estilo consistente entre as linhas.

História: Mensagens de commit e changelog simples

Nível: A2

História em inglês

Preparing release 1.3

Sam works on a small web app for an internal team. Last week, the team decided to prepare version 1.3. Before the release, Sam had to write a few commit messages. The team uses the imperative style: Add, Fix, Update, Remove. Sam opened a new branch to add a small feature for the dashboard.

Writing the commits

First, Sam wrote "Add export button to the dashboard". Then, he fixed a small bug and wrote "Fix date format in the report". He also updated the API client and wrote "Update API client to v2". A teammate asked why Sam used the imperative form and not the past simple. Sam explained that the imperative style is the convention for commit messages.

The changelog

After the commits, Sam wrote the release notes for version 1.3. He grouped the changes under three sections: Added, Fixed, Changed. In the changelog, past simple is also acceptable: "Added export button". Sam kept each line short and consistent. The team reviewed the changelog and approved the release.

Tradução linha por linha

Notas de vocabulário

• Add export button to the dashboard = mensagem de commit no imperativo; sem pronome, sem -ed, sem ponto final
• Fix date format in the report = imperativo para corrigir um bug em relatório
• Update API client to v2 = imperativo para atualizar uma dependência
• the imperative style = o estilo imperativo, convenção comum em commits
• the past simple = tempo verbal usado para narrar ações concluídas; aceitável em changelogs
• Added, Fixed, Changed = cabeçalhos clássicos de um changelog categorizado
• release notes = notas que resumem as mudanças de uma versão

Perguntas de compreensão

1. What version was the team preparing?
2. What style does the team use for commit messages?
3. What did Sam fix in the report?
4. Why did Sam use the imperative form instead of the past simple?
5. How did Sam group the changes in the changelog?
6. Did the team approve the release?

Prática com a história

1. Reescreva no imperativo: "Sam added an export button to the dashboard."
2. Escreva um bullet de changelog no past simple para a atualização do cliente de API.
3. Corrija a mensagem de commit: "I fixed a bug on the report page."
4. Escreva uma mensagem de commit para remover um endpoint antigo chamado /api/v1/users.