Guias de projetos

Modelo de notas de versão do GitHub para projetos de código aberto

Boas notas de versão informam ao usuário se deve atualizar e o que fazer depois. Uma lista de pull requests integrados oferece evidências úteis, mas raramente explica toda a experiência de atualização. Acrescente o impacto para o usuário e as ações necessárias antes de publicar.

Equipe editorial do GitHubStart · Atualizado

Comece com um modelo voltado ao usuário

Substitua cada campo entre colchetes por informações verificadas. Remova seções irrelevantes em vez de inventar funcionalidades. Se nenhuma ação de atualização for necessária, declare isso explicitamente após verificar o caminho de atualização compatível.

# [Versão] — [Data de lançamento]

## Destaques
- [Melhoria visível ao usuário e quem se beneficia]

## Atualização
- A partir de: [versão anterior compatível]
- Ação: [migração necessária ou nenhuma ação necessária]
- Verificação: [como confirmar uma atualização bem-sucedida]

## Mudanças incompatíveis
- [Comportamento alterado, usuários afetados e link de migração]

## Correções
- [Problema resolvido e link da issue ou do pull request]

## Problemas conhecidos
- [Limitação restante e solução alternativa]

## Colaboradores
[Dê crédito aos colaboradores e inclua o link do histórico completo de mudanças]

Transforme as notas geradas em uma explicação legível

O GitHub pode gerar notas com pull requests integrados, colaboradores e um link para o histórico completo de mudanças. Trate esse resultado como rascunho. Confira os limites da versão, remova entradas irrelevantes e agrupe as mudanças pelas tarefas que seus usuários realizam.

Por exemplo, “Corrigir caso limite do analisador” orienta pouco. Se for correto, explique que arquivos CSV com a última coluna vazia agora são importados corretamente e inclua o link da correção para detalhes técnicos. Não afirme que todos os problemas de análise foram resolvidos quando apenas um caso mudou.

Revise o caminho de atualização antes do anúncio

Experimente a atualização documentada a partir de uma versão anterior compatível. Confira os links de download e garanta que a documentação corresponda à versão. Diferencie uma prévia de uma versão estável e facilite encontrar as limitações restantes.

Publique as informações da versão antes de incluí-las em uma postagem na comunidade. Use o anúncio para destacar uma melhoria significativa, mantendo as notas de versão como referência detalhada. Registre as perguntas posteriores e esclareça as instruções quando necessário.

Perguntas frequentes

Notas de versão são o mesmo que um histórico de mudanças?

Há sobreposição. Um histórico registra mudanças ao longo do tempo; notas de versão explicam uma versão específica e seu efeito para os usuários. Conecte os dois com links para que o leitor possa alternar entre visão geral e detalhes.

Posso publicar notas geradas automaticamente sem alterações?

Revise-as primeiro. Os títulos de pull requests gerados podem omitir etapas de migração, impacto para o usuário ou problemas conhecidos.

Toda pequena mudança de código deve aparecer nos destaques?

Não. Reserve os destaques para mudanças importantes aos usuários e mantenha o histórico técnico detalhado no histórico de mudanças vinculado.

Referências