O blog da changeloop
Notas de versão, na prática
Duas coisas em que pensamos muito: como escrever notas de versão que alguém leia e como parar de manter um changelog à mão. Sem newsletter, sem cadastro. Só os textos.
Release notes de correção de bugs: entradas úteis
Release notes de correção de bugs funcionam quando cada entrada nomeia o sintoma, quem foi atingido e o próximo passo. Reescritas e regras de segurança.
Notas de versão na prática8 min de leitura
Como pedir feedback aos clientes em um produto de software
Faça uma pergunta específica logo depois que o usuário fizer algo, onde ele trabalha. Frases prontas para cada momento e os pedidos que você deve evitar.
Ciclo de feedback8 min de leitura
Exemplos de roadmap de produto: seis formatos e como falham
Seis exemplos de roadmap de produto com itens realistas: Now/Next/Later, trimestral, por temas, por resultados, público e de releases, e quando falham.
Ciclo de feedback8 min de leitura
Processo de gerenciamento de releases para entregas rápidas
Um processo de gerenciamento de releases em sete passos, com responsável e critério de saída para cada um, mais as métricas DORA e um KPI extra para medir.
Engenharia8 min de leitura
Exemplos de release notes para cada tipo de mudança
Exemplos de release notes para funcionalidade, correção, breaking change, segurança, depreciação, loja de apps e nota interna, com o porquê de cada texto.
Notas de versão na prática8 min de leitura
Versionamento da API do Stripe: como funciona e o que copiar
O versionamento da API do Stripe fixa cada conta em uma versão com data e permite sobrescrevê-la por requisição. Como funciona, o custo e o que copiar.
Mudanças de API8 min de leitura
Quem escreve o changelog, e quem deveria
Quem escreve o changelog? A autora do PR sabe o que mudou; a PM, por que importa. Nenhuma sozinha escreve uma entrada útil, e escolher uma o envelhece.
Engenharia6 min de leitura
Release notes de emergência sob pressão de tempo real
Releases disparadas por incidente precisam de notas escritas em minutos, não dias, e o processo normal de escrita assume um tempo que você não tem.
Notas de versão na prática6 min de leitura
Protobuf breaking changes: o que sobrevive no fio
Protobuf breaking changes acontecem no fio, não na URL. Mudanças de campo gRPC são grátis, outras quebram todo cliente em silêncio, mas parecem iguais.
Mudanças de API6 min de leitura
Formatos de arquivo de changelog: JSON, YAML ou só Markdown
O formato de um arquivo de changelog decide se ele alimenta uma página e um widget, ou só é lido por alguém. Markdown, JSON e YAML têm custos distintos.
Engenharia6 min de leitura
Pedidos duplicados: mesclar sem perder a voz original
Agrupar pedidos de funcionalidade duplicados protege a contagem. Mesclá-los sem cuidado perde a redação que tornava um deles útil, a perda menor.
Ciclo de feedback6 min de leitura
Mudanças de schema no GraphQL: depreciação sem versão
O GraphQL não tem v1 nem v2 na URL. Campos são depreciados um a um com uma diretiva, em um único schema compartilhado, e isso muda o que um changelog deve.
Mudanças de API6 min de leitura
Como escrever um guia de migração de API
Um guia de migração de API transforma uma mudança incompatível em checklist, não em interrupção. O que ele precisa ter, e por que uma entrada não basta.
Mudanças de API5 min de leitura
Um check de changelog para o GitHub Actions
Um check de changelog no GitHub Actions recusa o merge sem entrada, porque um passo que depende de memória falha num padrão previsível. E o que ele quebra.
Engenharia6 min de leitura
Recusar um pedido de funcionalidade sem perder a cliente
Fechar o ciclo geralmente significa dizer que algo foi lançado. A metade difícil é dizer não, de um jeito que não estrague a relação com a cliente.
Ciclo de feedback5 min de leitura
Release notes de feature flag: o que dizer, e quando
Release notes de feature flag separam merge e lançamento, que deixam de coincidir com um flag. Fechar o ciclo cedo anuncia uma funcionalidade invisível.
Ciclo de feedback6 min de leitura
Tickets de suporte vs. pedidos: em que confiar?
Um ticket de suporte e um quadro de pedidos medem coisas diferentes, e tratar um pico em um como no outro produz prioridades confiantes, mas erradas.
Ciclo de feedback5 min de leitura
Como rastrear pedidos de funcionalidades sem perdê-los
O rastreamento de pedidos falha de dois jeitos: não chegam a lugar nenhum, ou chegam onde ninguém revisita. Um sistema que resiste às duas falhas.
Ciclo de feedback6 min de leitura
Quando um pedido de funcionalidade é na verdade um bug
Um ticket de suporte pedindo uma configuração nova pode ser um contorno para um bug escondido. A etiqueta errada manda para a dona e a fila erradas.
Ciclo de feedback5 min de leitura
Tags do git, lançamentos e o seu changelog
Uma tag do git, um lançamento, uma entrada de changelog: três registros de um evento. Confundi-los faz o changelog se desviar. Como os três se encaixam.
Engenharia5 min de leitura
Changelogs de API internas: o que muda para o outro time
Um changelog de API pública tem um público que você não consegue contatar. Um interno tem um público a dois andares, e isso muda o que se deve a ele.
Mudanças de API6 min de leitura
Release notes internas: quem mais precisa saber
Suporte e vendas costumam descobrir um lançamento por um cliente confuso. Release notes internas resolvem isso, num formato diferente das notas ao cliente.
Notas de versão na prática5 min de leitura
Release notes para apps mobile: o que o limite corta
App Store e Play Store dão poucas linhas visíveis e sem link. O que funciona num changelog web quebra nesse limite, e os cortes precisam ser certos.
Notas de versão na prática5 min de leitura
Changelogs em monorepo: um só, ou um por pacote?
Um monorepo pode ter um changelog para o repositório inteiro ou um por pacote, e escolher errado deixa o lançamento barulhento demais ou espalhado demais.
Engenharia6 min de leitura
Como anunciar uma funcionalidade nova (sem silêncio)
A maioria dos anúncios de funcionalidades morre em um canal que ninguém lê duas vezes. Onde anunciar, o que dizer primeiro, e quem é preciso alcançar.
Notas de versão na prática5 min de leitura
Como priorizar pedidos de funcionalidades
Um backlog rastreado ainda deixa em aberto a pergunta difícil: qual pedido sai primeiro. Os frameworks que funcionam de verdade, e onde cada um falha.
Ciclo de feedback6 min de leitura
Release notes enterprise: o que muda para uma conta
Release notes enterprise para uma cliente em build privado precisam ser calibradas para a instância dela. Errar isso vaza o roadmap ou confunde o suporte.
Notas de versão na prática6 min de leitura
Semantic versioning e o seu changelog
Semantic versioning diz quanto um lançamento pode doer antes de ler uma palavra do changelog. O que cada número promete, e o que uma entrada deve a ele.
Engenharia5 min de leitura
Changelogs de webhook: o breaking change que ninguém pediu
Uma mudança no payload de um webhook quebra em silêncio, porque não há quem a rejeite. O que torna uma mudança de payload quebradora, e como versioná-la.
Mudanças de API6 min de leitura
O header Sunset da API, e quando enviar um
O header Sunset da API diz quando uma versão vai parar de responder, diferente de um aviso de depreciação. O que a RFC 8594 cobre e o que um brownout traz.
Mudanças de API6 min de leitura
Changelog: o que é, com um exemplo de entrada
Changelog é o registro datado do que mudou em um produto. Um exemplo de entrada, a diferença para release notes e commit log, e onde publicar o seu.
Notas de versão na prática6 min de leitura
Changelog de API: o que publicar e quem lê
Um changelog de API é lido por quem decide se o próprio código ainda vai funcionar no mês seguinte. O que cada entrada deve, onde ele vive e como assinar.
Mudanças de API7 min de leitura
Uma página de changelog que as pessoas realmente acompanham
Uma página de changelog vale a pena quando as pessoas voltam a ela. Onde ela vive, o que cada entrada precisa, feeds e markup, e onde o widget se encaixa.
Engenharia7 min de leitura
O template de e-mail de atualização de produto que é lido
O e-mail de atualização de produto que é lido foi enviado para quem pediu. Um template, os quatro tipos de e-mail, assuntos que funcionam, e consentimento.
Notas de versão na prática6 min de leitura
Como depreciar uma API sem perder seus desenvolvedores
Depreciação é uma promessa com uma data. O cronograma, o modelo de aviso, os headers de resposta, e o passo que impede um sunset de virar incidente.
Mudanças de API7 min de leitura
Melhores práticas de versionamento de API, para chamadores
Versione só o que quebra algo, coloque a versão onde os chamadores a vejam, e mantenha a antiga funcionando até uma data. Quatro esquemas comparados.
Mudanças de API8 min de leitura
Mudanças que quebram algo: o que conta e como lançá-las
Uma mudança que quebra algo é qualquer uma que um chamador correto não suportaria. O que conta, o que não conta, como pegá-la no CI e como lançá-la.
Mudanças de API10 min de leitura
Fechar o ciclo de feedback pelo changelog
Um ciclo de feedback fecha quando quem pediu sabe que foi lançado. O ciclo em quatro passos, onde quebra e por que o changelog é o lugar certo.
Ciclo de feedback8 min de leitura
Template de solicitação de recurso que vira changelog
Uma solicitação de recurso só serve se puder ser reencontrada no lançamento. O template, as etiquetas que o roteiam, e os campos que o changelog lê depois.
Ciclo de feedback6 min de leitura
Roadmap público a partir do seu issue tracker, três colunas
Um roadmap público é uma promessa sobre o futuro. Mantenha-o pequeno, alimente-o com suas issues, e mova cada item com uma etiqueta na própria issue.
Ciclo de feedback6 min de leitura
Automação de changelog, e seus limites
Automatize coleta, formatação e publicação. Não automatize seleção ou formulação. Onde a linha está e o que acontece cada vez que ela se move.
Engenharia6 min de leitura
Changelog vs release notes: qual é a diferença?
Um changelog é um registro contínuo para quem procura algo. Release notes são uma mensagem selecionada para quem decide se isso importa. A divisão.
Notas de versão na prática5 min de leitura
Dos conventional commits a um changelog
Conventional commits tornam um changelog derivável. Não o tornam legível. O que a convenção entrega, onde ela para, e como você preenche a lacuna.
Engenharia6 min de leitura
Como escrever release notes que as pessoas realmente leem
«Correções de bugs e melhorias de desempenho» não é uma release note. A pergunta que cada entrada deve responder, e a reescrita de uma nota real.
Notas de versão na prática6 min de leitura
Keep a Changelog, de fato implementado
A especificação é uma página e leva dez minutos para ler. Implementá-la é onde as equipes se desviam. O que ela diz, o que deixa aberto, e onde falha.
Engenharia6 min de leitura
Melhores práticas de release notes que valem a pena
A maioria das listas de melhores práticas é conselho de estilo. Estas mudam o que o leitor faz, e três populares que são puro culto da forma.
Notas de versão na prática6 min de leitura