<required> Avant de faire un travail quelconque, créez un élément de tâche/todo par étape applicable en utilisant vos outils de gestion de tâches disponibles (TaskCreate pour Claude, TodoWrite pour Copilot). Marquez chaque tâche in_progress quand vous la commencez et completed quand vous la terminez. Cela empêche que des étapes soient silencieusement ignorées à mesure que le contexte grandit. </required>

Examen des modifications d'API

Étape 1 : Identifier ce qui a changé

git diff $(git merge-base HEAD origin/main)...HEAD -- '**/api-report/**/*.md'

Créez un tableau résumé et présentez-le à l'utilisateur :

Types de modification : addition, suppression, changement de signature, promotion de tag.

Si toutes les modifications concernent exclusivement @internal, informez l'utilisateur qu'il n'y a pas de modifications d'API visibles pour les clients et arrêtez-vous.

Étape 2 : Vérifier les tags de release, la documentation et l'accessibilité des exports

Pour tout nouvel export, vérifiez que chacun possède un tag de release et signalez tout tag manquant à l'utilisateur — API Extractor échouera avec ae-missing-release-tag. Aidez l'utilisateur à choisir le bon tag :

En cas de doute : @alpha — plus facile à promouvoir qu'à rétrograder. @legacy est un modificateur associé (@legacy @public ou @legacy @alpha) pour les APIs v1 FF ; ne l'appliquez pas aux nouvelles APIs.

Pour tout nouvel export visible pour les clients (@public, @beta, @alpha) destiné à être utilisable par les consommateurs du package, vérifiez qu'il est accessible depuis le point d'entrée public du package, et non simplement exporté du module ou dossier adjacent. Tracez et mettez à jour la chaîne d'export à travers chaque barrel index.ts pertinent jusqu'au point d'entrée racine du package (généralement src/index.ts, ou des points d'entrée échelonnés comme src/alpha.ts / src/beta.ts le cas échéant). Les exports de barrel parent manquants constituent des modifications d'API incomplètes. API Extractor peut ne pas rapporter l'API prévue du tout, et les consommateurs sont censés importer depuis le point d'entrée de haut niveau du package plutôt que d'accéder à des sous-chemins.

Vérifiez également que chaque nouvel export visible pour les clients (@public, @beta, @alpha) possède une documentation TSDoc — au minimum un résumé, des tags @param et @returns si applicable. Signalez toute documentation manquante à l'utilisateur.

Étape 3 : Informer l'utilisateur de l'examen par l'API Council

Informez l'utilisateur si sa modification nécessite l'approbation de l'API Council :

Dites à l'utilisateur : l'approbation du council est un agrément distinct de l'examen du propriétaire du domaine. Pour engager le council, il peut contacter le membre API Council de son équipe EM ou taguer @FF API sur Teams. Partagez ce lien avec l'utilisateur pour plus de détails : https://eng.ms/docs/experiences-devices/opg/office-shared/fluid-framework/fluid-framework-internal/fluid-framework/docs/dev/resources/api-council

Étape 4 : Évaluer les changements cassants

Un changement cassant supprime ou modifie une API existante de manière à causer des erreurs de compilation pour les consommateurs qui mettent à jour.

@public / @legacy+@public

Si c'est un changement cassant pour @public ou @legacy @public, informez l'utilisateur que c'est probablement une erreur — les releases majeurs sont très rares. Les APIs @public cassantes doivent être coordonnées avec une release majeure ; l'ancienne API doit être dépréciée au moins 3 mois avant dans une release mineure avec un remplacement clair.

Partagez ces liens avec l'utilisateur pour le processus requis :

• Wiki API Deprecation : https://github.com/microsoft/FluidFramework/wiki/API-Deprecation
• Client 3.0 Breaking Changes tracking issue : https://github.com/microsoft/FluidFramework/issues/23271

@beta / @legacy+@alpha

Si c'est un changement cassant pour @beta ou @legacy @alpha, informez l'utilisateur :

• Les changements cassants ne peuvent être intégrés que dans des versions mineures qui sont un incrément de 10 (2.10, 2.20, 2.30, …)
• La PR doit être staged sur une branche test/breaks/client/#.#0/ et retenue jusqu'à l'ouverture de la fenêtre de rupture
• Il devrait vérifier si des partenaires (par ex. office-bohemia) consomment l'API directement — en cas de doute, supposez que c'est le cas et prévoyez 12 semaines de délai

Partagez ces liens avec l'utilisateur :

• Beta | Legacy Breaking Changes tracking issue : https://github.com/microsoft/FluidFramework/issues/25322
• Processus complet : https://github.com/microsoft/FluidFramework/wiki/Beta-Break-Process

@alpha uniquement

Informez l'utilisateur : bien que @alpha n'ait aucune garantie de stabilité contractuelle, il existe un accord informel de ne pas casser office-bohemia. Si ce changement pourrait casser office-bohemia, il devrait être staged en utilisant le même processus que ci-dessus.

En cas de doute, recommandez à l'utilisateur de tester d'abord contre office-bohemia en exécutant le pipeline d'intégration office-bohemia sur sa branche. Partagez ces liens :

• Office-bohemia integration pipeline : https://dev.azure.com/office/OC/_build?definitionId=29163
• Build - client packages pipeline : https://dev.azure.com/fluidframework/internal/_build?definitionId=12
• Instructions complètes : https://eng.ms/docs/experiences-devices/opg/office-shared/fluid-framework/fluid-framework-internal/fluid-framework/docs/dev/monitoring/loop-integration-pipeline/index

Informez également l'utilisateur : s'il saute cette vérification et que le changement casse office-bohemia, le pipeline d'intégration quotidien le détectera et FF OCE reviendra la PR ou le contactera pour qu'il le fasse dès que possible.

Étape 5 : Liste de vérification de la dépréciation

Si une API est en cours de dépréciation, vérifiez que ce qui suit est en place et signalez tout ce qui manque à l'utilisateur :

• [ ] Le commentaire TSDoc @deprecated inclut : version dépréciée, version de suppression, remplacement et un lien vers la tracking issue :

  /**
   * @deprecated 2.x.y. Supprimé en 3.0.0. Utilisez {@link replacementApi} à la place.
   * Voir {@link https://github.com/microsoft/FluidFramework/issues/ABCD} pour le contexte.
   */

• [ ] GitHub issue créée en utilisant le modèle "Deprecated API" comme sous-issue de la tracking issue appropriée
• [ ] Utilisation dans le codebase supprimée (les utilisations test-only peuvent subsister avec un commentaire explicatif)
• [ ] Changeset présent (voir Étape 6)

Partagez ce lien avec l'utilisateur pour une orientation complète sur la dépréciation : https://github.com/microsoft/FluidFramework/wiki/API-Deprecation

Étape 6 : Changeset

Tous les changements d'API visibles pour les clients nécessitent un changeset — additions, modifications, dépréciations, promotions de tag, suppressions.

Vérifiez qu'il existe : git status --porcelain -- .changeset/

Si aucun n'existe, créez-en un au nom de l'utilisateur depuis la racine du repo :

pnpm flub changeset add --empty

Cela crée un fichier nommé aléatoirement dans .changeset/. Éditez-le avec du contenu basé sur ce qui a changé. Le frontmatter YAML liste les packages affectés (seulement ceux significatifs pour les consommateurs) avec le type de bump minor, plus "__section" pour diriger vers la bonne section des notes de release : feature (nouvelles APIs), deprecation, breaking (majeur / serveur uniquement ; utilisez legacy pour les ruptures d'API legacy), tree (modifications des APIs SharedTree/@fluidframework/tree), fix, ou other.

Règles de la ligne de résumé (de .changeset/README.md) : succincte, pas de ponctuation terminale, pas de formatage backtick, temps présent. Test de préfixe : prépendez mentalement « Dans cette release, » pour vérifier que c'est naturel. Le corps peut inclure un exemple de code pour les features, dépréciations et changements cassants.

Après avoir rédigé le changeset, affichez le contenu à l'utilisateur et confirmez qu'il a l'air correct avant de poursuivre.

Étape 7 : Résumé

Présentez à l'utilisateur un résumé clair :

1. Modifications d'API trouvées (tableau de l'Étape 1)
2. Tout tag de release ou documentation manquants
3. Si l'examen par l'API Council est requis
4. Tout avertissement de changement cassant et le processus que l'utilisateur doit suivre
5. Tout problème de dépréciation
6. Statut du changeset

Terminez avec un go/no-go clair : « Vos modifications semblent bonnes pour la fusion » ou « Veuillez résoudre ces problèmes avant la fusion : … »