Comment rédiger les notes de mise à jour ?

Question

Existe-t-il des directives ou des bonnes pratiques sur la façon dont les notes de mise à jour doivent être rédigées ? Je suppose que j'essaie de trouver le juste équilibre entre la nécessité de faire passer le message sans être trop précis. Par ailleurs, les développeurs ont-ils l'habitude de fournir à l'équipe d'assurance qualité un plus grand nombre de notes de version que celles qui sont soumises au public ?

Answer 1

Les notes de diffusion publique doivent contenir au moins :

• version, numéro de série
• tous les bogues publics corrigés
• toutes les fonctionnalités publiques ajoutées

Les notes de version d'AQ doivent contenir au moins :

• version, numéro de série
• tous les bogues corrigés, y compris le numéro du bogue
• toutes les fonctionnalités ajoutées, y compris les liens vers les documents de conception

Considérez votre public et essayez de penser à ce dont il a besoin.

Une autre chose à ajouter est le support nouveau ou interrompu pour certaines plateformes. (Par exemple, nous avons abandonné le support de Win3.1 et ajouté Vista 64 bit).

Answer 2

Je jetterais un coup d'œil aux notes de publication des projets F/OSS populaires :

• Firefox
• GIMP
• Ubuntu
• Android
• TeamCity
• etc.

Tous ces projets ont des notes de publication assez lisibles et équilibrées.

Answer 3

Si vous disposez d'un système de gestion de projet/suivi des problèmes, vous devez absolument l'utiliser pour générer vos notes de publication. Trac y Redmine en particulier sont très bons pour cela.

Les points de libération devraient avoir quelques propriétés, IMO :

• N'oubliez pas votre public. S'il s'agit d'une application iPhone, peu de gens vont se soucier du fait qu'une erreur logique particulière à la ligne 572 de la classe Foo a été corrigée. Mais ils se soucieront beaucoup de "l'application est maintenant sensible à l'accéléromètre".
• Résumez les nouveaux développements, les nouvelles fonctionnalités et les corrections de bogues de manière générale, si possible. Si vous pouvez les relier entre eux de manière thématique (par exemple, "nous avons implémenté les génériques et les types anonymes"), un court texte à ce sujet est un bon moyen de donner aux gens une vue d'ensemble.
• Détaillez les éléments spécifiques qui ont été corrigés, avec des liens vers votre système public de suivi des bogues, le cas échéant. Cela peut généralement être généré automatiquement.
• Ne donnez pas de détails atroces. Un résumé d'une ou deux lignes de chaque élément ajouté ou corrigé devrait suffire.
• Incluez toujours des identifiants de version spécifiques (par exemple, "v.1.4.5"), le cas échéant.

Answer 4

Cela dépend vraiment de l'audience. Pour les utilisateurs techniques (par exemple les développeurs qui utilisent votre API), vous pouvez être très technique. D'un autre côté, les utilisateurs finaux de haut niveau d'une application que vous avez créée peuvent n'être intéressés que par les nouvelles fonctionnalités et les changements majeurs.

Entre les deux, il y a les utilisateurs non techniques qui ont aussi besoin de détails, par exemple le service d'assistance. Pour ces personnes, vous pouvez donner une description détaillée sans les spécificités techniques de bas niveau, par exemple "Corriger un bug où l'enregistrement n'était pas sauvegardé dans la base de données".

Answer 5

À mon avis, l'une des meilleures pratiques en matière de notes de mise à jour est l'automatisation. S'il existe certaines meilleures pratiques pour les messages de soumission du système de contrôle des révisions ( http://drupal.org/node/52287 ), vous pouvez créer des notes de version par un script automatisé ( http://cvs.drupal.org/viewvc.py/drupal/contributions/tricks/cvs-release-notes/ ). Cela permettrait de créer de très belles notes de mise à jour : http://drupal.org/node/226165