Escreva um registro de alterações que diga o que mudou e o que fazer

## Descubra quem lê o registro de alterações e quais mudanças afetam essas pessoas Escreva um registro de alterações para as pessoas afetadas pelas mudanças no software, não como uma especificação validada por máquina nem como um despejo bruto da atividade de desenvolvimento. Cada decisão editorial deve ajudar o leitor a entender a versão publicada com menos esforço. Antes de começar a redação, identifique: - O lançamento ou a versão que está sendo descrita. - As pessoas que dependem do produto, da biblioteca, do serviço ou da documentação. - As mudanças que alteram o comportamento, as expectativas, a compatibilidade, a acessibilidade, a segurança ou as ações exigidas. - As convenções estabelecidas de versionamento, títulos e entradas que o projeto já utiliza. Use as convenções como ferramentas, não como substitutas do discernimento. Preserve uma estrutura existente quando ela ajudar os leitores a comparar versões, mas não force uma mudança a adotar uma redação enganosa apenas para satisfazer um rótulo. Quando uma regra precisar ser rígida, explique o motivo para que as pessoas colaboradoras possam aplicá-la de modo consciente. Mantenha os princípios do registro de alterações separados das instruções de configuração e dos procedimentos rotineiros de contribuição. Mantenha um único local oficial para cada tipo de orientação e crie links para ele, em vez de duplicar instruções que podem divergir com o tempo. ## Inclua só as mudanças que afetam quem lê e diga por que importam Analise as mudanças candidatas pela perspectiva do leitor. Inclua um item quando ele alterar o que uma pessoa pode fazer, observar, considerar confiável, configurar, migrar ou proteger. Exclua atividades internas que não tenham efeito significativo, a menos que expliquem uma consequência operacional ou de compatibilidade relevante. Para cada mudança incluída, responda: 1. O que mudou em termos observáveis? 2. Quem é afetado e em quais condições? 3. Por que a mudança é importante? 4. O leitor precisa agir e, em caso afirmativo, qual ação é necessária? Comece pelo resultado. Acrescente apenas o contexto necessário para evitar mal-entendidos. Declare explicitamente as condições, as exceções e as implicações para a migração; não as esconda atrás de um resumo vago. Não promova determinada ferramenta apenas porque ela é popular e não invente um processo que não resolva nenhum problema de comunicação demonstrado. Prefira uma entrada simples e o fluxo de trabalho já existente no projeto, a menos que a abordagem atual impeça os leitores de entender uma mudança importante. Diretrizes e recomendações devem incluir sua justificativa. O leitor deve ser capaz de discordar de forma consciente, porque a relação de compromisso e o benefício pretendido estão visíveis. ## Escreva cada mudança em palavras simples, com o efeito e o que é preciso fazer Use linguagem simples e apresente primeiro o ponto principal. Evite barreiras excludentes, abreviações internas, complexidade ornamental e frases que obriguem o leitor a reconstruir a afirmação principal. Prefira uma redação que um leitor não nativo consiga entender na primeira leitura e que possa ser traduzida diretamente, em vez de exigir uma nova interpretação de quem traduz. Mantenha estes elementos separados: - A mudança em si: uma descrição concreta do comportamento anterior e do novo. - O impacto: os usuários, ambientes, versões ou fluxos de trabalho afetados. - O motivo: o problema resolvido ou o princípio protegido. - A ação: qualquer etapa de atualização, configuração, migração ou verificação que o leitor precise realizar. Não exagere a certeza nem o impacto. Se o comportamento variar conforme o contexto, indique a condição em vez de emitir uma ordem universal. Se nenhuma ação do leitor for necessária, não invente uma. Use a terminologia de maneira consistente entre entradas e versões. Explique os termos técnicos inevitáveis no primeiro uso, preserve distinções importantes e evite eufemismos que enfraqueçam alertas ou informações sobre mudanças incompatíveis. Aplique o mesmo estilo claro e focado no ponto principal à documentação relacionada, às notas de contribuição e às mensagens de commit, para que o registro de alterações seja respaldado por informações de origem consistentes. ## Confira se as traduções dizem o mesmo que o original e deixe uma pessoa decidir Trate as traduções como parte essencial da comunicação de mudanças. Uma tradução específica de uma versão deve existir ou oferecer orientações claras para que alguém contribua com ela. Ela deve permanecer correta e consistente com a fonte canônica, além de ser compreensível em seu próprio idioma e contexto cultural. Mantenha a estrutura da página, o roteamento de versões e a marcação da fonte simples o bastante para que uma pessoa tradutora que não seja programadora consiga editá-los. Antes de alterar títulos, identificadores, relações entre versões ou convenções de marcação, avalie como a mudança afeta todos os idiomas e versões mantidos. Use esta sequência de revisão: 1. Finalize o significado da entrada canônica antes da tradução. 2. Registre quais versões e idiomas exigem a mudança. 3. Verifique se cada tradução necessária existe ou se há um caminho claro para contribuir com ela. 4. Compare o significado traduzido com a fonte canônica para detectar omissões, inversões, condições alteradas e terminologia inconsistente. 5. Peça a uma pessoa que conheça o idioma e a cultura que tome a decisão editorial final. Não use texto gerado por máquina como substituto de uma pessoa tradutora. Verificações automatizadas ou assistidas por modelos podem localizar lacunas de cobertura e possíveis inconsistências, mas as pessoas são responsáveis pelo significado, pela adequação cultural e pela redação final. ## Deixe as verificações repetidas para ferramentas simples e as decisões para as pessoas Use automação para reduzir verificações repetitivas entre idiomas, versões e ambientes de apresentação. Bons candidatos incluem verificações de cobertura de tradução, testes de roteamento de versões, recursos de apoio à comparação semântica, verificações de acessibilidade e testes de regressão visual ou funcional. Prefira ferramentas comuns e reutilizáveis que, depois de criadas, possam ser executadas localmente ou sem conexão, sem um modelo. Um modelo de linguagem pode ajudar uma vez a projetar ou implementar uma ferramenta, mas a verificação resultante deve ser inspecionável, repetível, econômica para executar e capaz de funcionar por conta própria. Os modelos não devem: - Substituir tradutores humanos nem a revisão cultural. - Decidir as posições editoriais do projeto ou o significado de suas orientações. - Justificar um recurso ou processo que não tenha uma necessidade independente. As pessoas decidem se uma entrada do registro de alterações é correta, útil e apropriada. As ferramentas fornecem evidências; elas não são responsáveis pela conclusão. Mantenha o sistema de publicação simples e durável. Prefira a cadeia atual de ferramentas de compilação e autoria e acrescente uma dependência, um serviço, um banco de dados ou um novo ambiente de execução apenas quando uma exigência concreta não puder ser atendida com segurança pela abordagem atual. Ferramentas de verificação exclusivas para o desenvolvimento não devem se tornar requisitos desnecessários de produção. Antes de publicar, confirme que a entrada canônica está clara, que as versões e traduções necessárias estão cobertas, que as verificações automatizadas produziram resultados reais e que uma pessoa revisou o significado final.