Maintenance des packages Dart

Directives pour maintenir les packages Dart en conformité avec les bonnes pratiques de l'équipe Dart.

Découverte

Pour trouver les tâches de maintenance ou les incohérences :

Vérifications de cohérence

Assurez-vous que la version la plus récente dans CHANGELOG.md correspond à pubspec.yaml :

• Comparez le premier en-tête dans CHANGELOG.md avec le champ version: dans pubspec.yaml.

Versioning

Semantic Versioning

• Major : Changements qui cassent la compatibilité.
• Minor : Nouvelles fonctionnalités (changements d'API non-cassants).
• Patch : Corrections de bugs, documentation ou changements sans impact.
• Packages instables : Utilisez 0.major.minor+patch.
• Recommandation : Visez 1.0.0 dès que le package est stable.

Vérification pré-édition

• Vérifier les versions publiées : Avant de modifier CHANGELOG.md ou pubspec.yaml, TOUJOURS vérifier la version actuellement publiée (par ex. via git tag ou pub.dev).

• Ne pas modifier les versions publiées : Ne jamais ajouter de nouvelles entrées à un en-tête de version qui correspond à une release publiée.

• Incrémenter pour les nouveaux changements : Si la version actuelle dans pubspec.yaml correspond à une release publiée, incrémenter la version (par ex. généralement en -wip) et créer une nouvelle section dans CHANGELOG.md.

  • Cohérence : L'en-tête CHANGELOG.md doit correspondre à la nouvelle version pubspec.yaml.

  • Directives SemVer :

    • Changements cassants : Incrémenter Major, réinitialiser Minor/Patch (ex. 2.0.0-wip, 0.5.0-wip).
    • Nouvelles fonctionnalités : Incrémenter Minor, réinitialiser Patch (ex. 1.1.0-wip, 0.4.5-wip).
    • Corrections de bugs : Incrémenter Patch (ex. 1.0.1-wip).

Contenu du changelog

• Centré sur l'impact utilisateur : Les entrées dans CHANGELOG.md doivent se concentrer sur les changements visibles ou impactant l'utilisateur final (ex. nouvelles fonctionnalités, corrections de bugs, changements cassants).
• Omettre les changements internes : N'incluez pas les refactorisations internes, les changements de tests ou autres modifications qui n'affectent pas le comportement ou l'API du package pour l'utilisateur.

Versions en cours (WIP)

• Immédiatement après une publication, ou au premier changement après une publication, mettez à jour pubspec.yaml et CHANGELOG.md avec le suffixe -wip (ex. 1.1.0-wip).
• Cela indique que l'état actuel n'est pas encore publié.

Changements cassants

• Évaluez l'impact sur les packages dépendants et les projets internes.
• Envisagez de faire passer les changements par les presubmits internes si possible.
• Préférez les déploiements progressifs (ex. nouveau comportement en opt-in) pour minimiser les casses en aval.

Processus de publication

1. Préparation : Supprimez le suffixe -wip de pubspec.yaml et CHANGELOG.md dans une pull request dédiée.
2. Exécution : Exécutez dart pub publish (ou flutter pub publish) et résolvez tous les avertissements et erreurs.
3. Étiquetage : Créez et poussez une balise git pour la version publiée :
   • Pour les repos à package unique : v1.2.3
   • Pour les monorepos : package_name-v1.2.3
   • Exemple : git tag v1.2.3 && git push --tags

Gestion des pull requests

• Commits : Chaque PR devrait généralement correspondre à un commit unique fusionné.
• Historique partagé : Une fois qu'une PR est ouverte, évitez le force push sur la branche.
• Résolution des conflits : Préférez fusionner main dans la branche de PR plutôt que de rebaser pour résoudre les conflits. Cela préserve l'historique de révision et les commentaires.
• Révision : Ajoutez des commentaires depuis la vue "Files changed" pour les regrouper.
• Inspection locale : Utilisez gh pr checkout <number> pour inspecter les changements localement dans votre IDE.