Uma entrada do registo de alterações descreve uma mudança confirmada: versão, data efetiva, utilizadores abrangidos, comportamento anterior e novo e ação necessária. Esta estrutura trata uma funcionalidade já disponibilizada, não um primeiro lançamento.
Reunir factos sobre uma mudança
Confirme com o responsável o nome da funcionalidade, identificador da versão, momento real da disponibilização e utilizadores abrangidos. Uma data prevista não é uma data efetiva. Se o acesso for restrito, identifique o grupo.
O pedido interno ajuda a recuperar decisões, mas não substitui a descrição para clientes. O texto deve ser compreensível sem notas internas.
Registar versão e data
Use o identificador adotado pelo produto. Não invente um número para o artigo. Quando existir SemVer, interprete os componentes segundo as suas regras e a API pública declarada. Outros sistemas podem ter significados diferentes.
Escreva a data sem ambiguidade, por exemplo YYYY-MM-DD, e o fuso quando a hora importar. A data de redação pode ser diferente. Numa disponibilização gradual, indique o início e o alcance atual.
Descrever antes e depois
Explique o comportamento observado antes e após a alteração, quem é afetado, limites e passos necessários. Se não houver ação do utilizador, diga-o explicitamente.
Não atribua vantagens não verificadas. Alterar filtros não demonstra mais vendas ou horas poupadas. Preços e faturação pertencem à documentação correspondente.
Exemplo de uma entrada
Este exemplo fictício não descreve uma versão do Semly.
- Funcionalidade: filtrar uma lista de documentos.
- Versão: 2.4.1 segundo a numeração do produto ilustrativo.
- Data efetiva: 2026-10-12.
- Antes: selecionar um segundo filtro removia o primeiro.
- Depois: a lista aplica ambos os filtros.
- Abrangência: utilizadores da lista na versão 2.4.1.
- Ação: atualizar a lista aberta após a atualização.
- Limite: modelos de filtros guardados não são alterados.
O limite evita pressupostos sobre os modelos. Num caso real, acrescente uma ligação verificada à documentação. Sem documentação, explique o passo e não invente uma URL.
Verificar antes de guardar
Compare versão, data, abrangência e comportamento com a confirmação da equipa. Verifique a ação e as ligações.
Um leitor sem conhecer o pedido deve perceber o que mudou e quando. Funcionalidades independentes têm entradas separadas na versão, mas a mesma alteração não precisa de vários artigos.
Preservar o significado nas traduções
Mantenha identificador, momento, abrangência e limites. Outra língua não confirma acesso noutro mercado.
Numa correção editorial, preserve a data real de disponibilização e identifique separadamente a atualização do texto. Ela não é uma nova disponibilização.
Fonte sobre numeração
SemVer refere-se a uma API pública declarada. Não é obrigatório para todas as aplicações SaaS.
