Maintenance de Paquets Dart

Directives pour maintenir les paquets Dart en conformité avec les meilleures 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 l'en-tête supérieur dans CHANGELOG.md avec le champ version: dans pubspec.yaml.

Versioning

Versioning Sémantique

• Major : Changements incompatibles.
• Minor : Nouvelles fonctionnalités (changements d'API non-incompatibles).
• Patch : Corrections de bogues, documentation, ou changements sans impact.
• Paquets instables : Utilisez 0.major.minor+patch.
• Recommandation : Visez 1.0.0 dès que le paquet est stable.

Vérification Avant Modification

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

• Ne Pas Modifier les Versions Publiées : N'ajoutez jamais de nouvelles entrées à un en-tête de version qui correspond à une balise publiée.

• Incrémenter pour les Nouveaux Changements : Si la version actuelle dans pubspec.yaml correspond à une balise publiée, incrémentez la version (par exemple, généralement à -wip) et créez une nouvelle section dans CHANGELOG.md.

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

  • Directives SemVer :

    • Changements Incompatibles : Augmentez Major, réinitialisez Minor/Patch (par exemple, 2.0.0-wip, 0.5.0-wip).
    • Nouvelles Fonctionnalités : Augmentez Minor, réinitialisez Patch (par exemple, 1.1.0-wip, 0.4.5-wip).
    • Corrections de Bogues : Augmentez Patch (par exemple, 1.0.1-wip).

Contenu du Changelog

• Concentrez-vous sur l'Impact Utilisateur : Les entrées dans CHANGELOG.md doivent se concentrer sur les changements visibles ou impactant l'utilisateur final (par exemple, nouvelles fonctionnalités, corrections de bogues, changements incompatibles).
• Omettez les Changements Internes : N'incluez pas les refactorisations internes, les changements de tests, ou autres modifications qui n'affectent pas le comportement du paquet ou l'API pour l'utilisateur.

Versions Work-in-Progress (WIP)

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

Changements Incompatibles

• Évaluez l'impact sur les paquets dépendants et les projets internes.
• Envisagez d'exécuter les changements via des presubmits internes si possible.
• Préférez les déploiements progressifs (par exemple, nouveau comportement en opt-in) pour minimiser les cassures 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 à paquet 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 doit généralement correspondre à un seul commit compressé lors de la fusion.
• Historique Partagé : Une fois qu'une PR est ouverte, évitez de faire un force push sur la branche.
• Résolution de Conflits : Préférez fusionner main dans la branche 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 à partir de la vue "Files changed" pour les regrouper.
• Inspection Locale : Utilisez gh pr checkout <number> pour inspecter les changements localement dans votre IDE.