Guides de projets

Modèle de notes de version GitHub pour les projets open source

De bonnes notes de version indiquent à l’utilisateur s’il doit effectuer la mise à niveau et comment procéder. Une liste de pull requests fusionnées fournit des éléments utiles, mais explique rarement l’ensemble du parcours de mise à niveau. Ajoutez les conséquences pour les utilisateurs et les actions nécessaires avant publication.

Équipe éditoriale de GitHubStart · Mis à jour

Commencez par un modèle centré sur l’utilisateur

Remplacez chaque champ entre crochets par des informations vérifiées. Supprimez les sections inutiles plutôt que d’inventer des fonctionnalités. Si aucune action n’est nécessaire pour la mise à niveau, indiquez-le explicitement après avoir vérifié le parcours pris en charge.

# [Version] — [Date de publication]

## Points forts
- [Amélioration visible pour l’utilisateur et bénéficiaires]

## Mise à niveau
- Depuis : [version précédente prise en charge]
- Action : [migration nécessaire ou aucune action requise]
- Vérification : [comment confirmer la réussite de la mise à niveau]

## Ruptures de compatibilité
- [Comportement modifié, utilisateurs concernés et lien de migration]

## Correctifs
- [Problème résolu et lien vers le ticket ou la pull request]

## Problèmes connus
- [Limitation restante et solution de contournement]

## Contributions
[Remerciez les contributeurs et ajoutez un lien vers le journal complet des modifications]

Transformez les notes générées en explication lisible

GitHub peut générer des notes contenant les pull requests fusionnées, les contributeurs et un lien vers le journal complet des modifications. Considérez ce résultat comme un brouillon. Vérifiez le périmètre de la version, retirez les entrées inutiles et regroupez les modifications selon les tâches de vos utilisateurs.

Par exemple, « Corriger un cas limite de l’analyseur » donne peu d’indications. Si c’est exact, expliquez que les fichiers CSV dont la dernière colonne est vide sont désormais importés correctement, et liez le correctif pour les détails techniques. N’affirmez pas que tous les problèmes d’analyse sont résolus si un seul cas a changé.

Vérifiez le parcours de mise à niveau avant l’annonce

Essayez la mise à niveau documentée depuis une version précédente prise en charge. Vérifiez les liens de téléchargement et la correspondance entre documentation et version. Distinguez une préversion d’une version stable et rendez les limitations restantes faciles à trouver.

Publiez les informations de version avant de les lier depuis un message communautaire. Utilisez l’annonce pour mettre en avant une amélioration significative, les notes de version restant la référence détaillée. Recueillez les questions qui suivent et clarifiez les instructions si nécessaire.

Questions fréquentes

Les notes de version sont-elles identiques à un journal des modifications ?

Leurs contenus se recoupent. Un journal consigne les modifications au fil du temps ; les notes de version expliquent une version donnée et ses effets sur les utilisateurs. Reliez-les pour permettre de passer de la vue d’ensemble aux détails.

Puis-je publier les notes générées automatiquement telles quelles ?

Relisez-les d’abord. Les titres de pull requests générés peuvent omettre les étapes de migration, les conséquences pour l’utilisateur ou les problèmes connus.

Chaque petite modification de code doit-elle figurer dans les points forts ?

Non. Réservez les points forts aux changements importants pour les utilisateurs et conservez l’historique technique détaillé dans le journal des modifications lié.

Références