Projeto A2: bug report, PR e release simples

Nível: A2

Objetivo

Integrar habilidades A2 em um mini-projeto de software: abrir ticket com reprodução, resumir um PR em poucas frases, responder a um review e comunicar uma release em inglês claro e profissional.

Explicação

Este tópico junta cinco habilidades do A2 em um único fluxo de trabalho: do bug aberto ao release no ar. Em cada etapa, frases curtas, voz ativa e listas funcionam melhor do que parágrafos longos.

1. Abrir ticket. O título deve ser uma frase que descreve o sintoma, não uma opinião genérica.

• `Apply coupon code returns 500 on checkout` (bom: sintoma + local)
• `Bug in coupon` (ruim: vago, sem sintoma)
• `It doesn't work` (ruim: não diz o que aparece)

No corpo do ticket, cinco blocos curtos: steps to reproduce (1, 2, 3...), expected (o que deveria acontecer), actual (o que realmente acontece), environment (navegador, SO, build) e severity (High/Medium/Low).

2. Descrever a reprodução. Os passos vão em uma lista numerada, cada um com uma ação no imperativo:

`1) Add an item to the cart. 2) Go to checkout. 3) Enter the code SAVE10. 4) Click Apply.`

Evite explicações longas no meio dos passos — coloque-as em uma nota à parte. Use a forma `Enter` (não `Enters` nem `Entering`).

3. Resumir um PR. O título segue a convenção de commit: imperativo curto, sem pronome: `Fix 500 error on coupon code apply`. A descrição tem 1-3 frases curtas, no estilo `This PR fixes...` + `It adds...` + `It updates...`.

• `This PR fixes issue #4321. It adds a check for empty codes and updates the test.`

4. Responder a um review. Combine agradecimento com confirmação curta:

• `Thanks for the review. Done. Pushed the new version.`
• `Good catch. Done.`
• `Will do. Pushing in a few minutes.`

Responder só `OK` ou `Done` soa curto demais; o `Thanks for the review` abre a conversa de forma profissional.

5. Comunicar uma release. Em um canal ou e-mail, três blocos curtos:

• Versão: `We just released v1.4.`
• O que inclui: `It includes the coupon fix and a new test.`
• Pedido de feedback: `Please report any issues in this channel.`

Em todo o fluxo, prefira frases curtas, voz ativa, listas numeradas ou com bullet points, e um único ponto por frase. Esse é o tom neutro de equipes de engenharia em inglês.

Exemplos

Erros comuns

• Usar títulos vagos no ticket: `Bug` ou `It doesn't work` devem ser substituídos por uma frase que descreve o sintoma, como `Apply coupon returns 500 on checkout`.
• Colocar explicação longa no meio dos passos: `1) Add an item, this happens because the API is slow...` deve ser quebrado em passos curtos e uma nota à parte.
• Inverter expected e actual: o expected vem sempre antes e descreve o comportamento correto; o actual descreve o que de fato acontece.
• Escrever a descrição do PR no past simple: `I fixed the coupon bug` deve virar `Fix 500 on coupon apply` no título e `This PR fixes...` na descrição.
• Responder ao review só com `OK` ou `Done` sem agradecer: `Thanks for the review` abre a resposta; depois vêm `Done` ou `Pushed the new version`.
• Comunicar release sem a versão: `We released the new thing` deve incluir o número, como `We just released v1.4`.
• Fechar a release só com `Thanks` em vez de um pedido: prefira `Please report any issues in this channel`.

Prática guiada

Monte as cinco peças do projeto a partir do mesmo bug (cupom retorna 500 no checkout):

1. Título do ticket: `Apply coupon code returns 500 on checkout`
2. Passos para reproduzir: `1) Add an item. 2) Go to checkout. 3) Enter SAVE10. 4) Click Apply.`
3. Expected/Actual: `Expected: the page shows the new total. Actual: the page shows a 500 error.`
4. PR: título `Fix 500 error on coupon code apply`; descrição `This PR fixes issue #4321. It adds a check for empty codes and updates the test.`
5. Resposta ao review: `Thanks for the review. Done. Pushed the new version.`
6. Release note: `We just released v1.4. It includes the coupon fix and a new test. Please report any issues in this channel.`

Observe que em todas as peças há: frase curta, voz ativa, lista numerada ou com bullet points, e uma única ideia por frase. Esse é o tom comum de equipes de engenharia em inglês.

Resumo

O projeto A2 junta cinco peças em um só fluxo: ticket com título claro e passos curtos de reprodução, expected/actual, descrição curta de PR no estilo 'This PR fixes...', resposta educada ao review com agradecimento e confirmação, e release com versão + o que inclui + pedido de feedback. Em todas elas, prefira frases curtas, voz ativa, listas numeradas e um único ponto por frase.

História: Projeto A2: bug report, PR e release simples

Nível: A2

História em inglês

A new bug report

On Tuesday morning, a customer reported a problem with the checkout page. Sam checked the issue and opened a ticket. The title was short: "Apply coupon code returns 500 on checkout." He listed the steps to reproduce: 1) Add an item to the cart. 2) Go to checkout. 3) Enter the code SAVE10. 4) Click Apply. Expected: the page shows the new total. Actual: the page shows a 500 error. Environment: Chrome 120, Windows 11. Severity: High.

The pull request

Sam found the bug in the coupon validator. He wrote a small test and fixed the issue. Then he opened a pull request: "Fix 500 error on coupon code apply." The description was short: "This PR fixes issue #4321. It adds a check for empty codes and updates the test." He asked Anna to do a code review on the change.

Review and release

Anna left two comments on the PR. The first comment was a NIT: "NIT: could you rename 'tmp' to 'discount'?" The second comment asked for a test: "Could you add a test for the empty case?" Sam updated the code and pushed the new version to the branch. He answered: "Thanks for the review. Done. Pushed the new version." On Friday, the team shipped version 1.4. Sam wrote a short note in the channel: "We just released v1.4. It includes the coupon fix and a new test. Please report any issues in this channel." The customer answered: "Thanks, the checkout works again."

Tradução linha por linha

Notas de vocabulário

• Apply coupon code returns 500 on checkout = Título de ticket com sintoma e local; evite títulos vagos como 'Bug' ou 'It doesn't work'.
• steps to reproduce = Lista numerada de ações no imperativo; uma ação por linha.
• Expected: ... Actual: ... = Pares nesta ordem, descrevendo o comportamento correto e o erro real.
• This PR fixes issue #4321. It adds a check for empty codes and updates the test. = Descrição de PR em duas frases: o que fecha + o que muda.
• Thanks for the review. Done. Pushed the new version. = Resposta de review: agradecimento + confirmação curta da ação.
• We just released v1.4. It includes the coupon fix and a new test. Please report any issues in this channel. = Release note: versão com 'We just released', mudanças com 'It includes', pedido com 'Please report any issues'.

Perguntas de compreensão

1. What problem did the customer report?
2. What was the ticket title?
3. What was the severity of the bug?
4. What was the title of the pull request?
5. What did the second comment from Anna ask for?
6. How did Sam answer Anna after pushing the new version?
7. What version did the team release, and what did it include?

Prática com a história

1. Reescreva este título vago de ticket como uma frase específica: 'Bug in coupon'
2. Escreva uma descrição curta de PR (2 frases) que fecha a issue #4321 e adiciona um teste para o caso vazio.
3. Responda a este NIT de forma curta e educada: 'NIT: could you rename the variable tmp to discount?'
4. Escreva uma release note curta (2-3 frases) para a v1.5 que inclui a correção do cupom e dois novos testes.