Publication client Fluid Framework

Workflow de publication pour le groupe de publication client. Supporte deux modes : interactif (par défaut) et autonome.

Détection de l'environnement

Vérifiez la variable d'environnement CI au début de chaque session :

• CI=true : Exécution dans un workflow GitHub Actions. Utilisez uniquement origin (pas upstream). Utilisez des commandes sûres pour CI (voir Alternatives de commandes sûres pour CI). Ne demandez jamais d'entrée. Enregistrez les blocages et les complétions de phase dans la sortie du workflow pour examen humain.
• CI non défini ou false : Exécution locale. Utilisez la détection upstream/origin comme décrit dans Key Context.

Sélection du mode

Au début de chaque session de publication, posez la question à l'utilisateur :

Souhaitez-vous exécuter en mode interactif ou autonome ?

En CI (CI=true), utilisez toujours le mode autonome — ne posez pas la question.

Mode interactif (par défaut)

Exécutez les commandes de manière autonome mais pausez avant de créer des PR, de pousser des branches ou de déclencher des builds. Demandez une confirmation de version aux points clés. C'est le comportement actuel.

Mode autonome

Exécutez la phase sélectionnée entièrement d'un bout à l'autre sans pause. Détectez automatiquement l'état de la publication à partir du calendrier et du repo (voir ci-dessous). Si l'utilisateur fournit les informations de version à l'avance, ignorez entièrement les questions de version.

Exigences :

• Informations de version à l'avance : L'utilisateur doit fournir tous les numéros de version avant de commencer (version de publication actuelle et/ou version suivante, selon la phase). Ne posez pas de questions de version en cours d'exécution. Si l'utilisateur ne fournit pas les versions, détectez-les à partir du calendrier et de l'état du repo (voir ci-dessous).
• Aucune pause de confirmation : Créez des PR, poussez des branches et exécutez flub release sans demander. Incluez des messages de commit et des descriptions de PR clairs.
• Exécution limitée à la phase : Chaque phase s'exécute jusqu'à son terme, puis rapporte ce que l'utilisateur doit faire ensuite (par ex., « mettre en file d'attente le build ADO » ou « attendre les feeds npm, puis réinvoquer pour les mises à jour des tests de type »).
• Recours aux problèmes : Si une étape échoue (erreurs de permission, défaillances de commandes sûres pour CI, rejet de git push, ou toute autre erreur empêchant la progression), arrêtez et ouvrez un problème GitHub dans microsoft/FluidFramework décrivant ce qui a été complété, ce qui a échoué et ce qui reste. Utilisez le format de titre Release <VERSION>: <brief description> et étiquetez-le avec release-blocking. Incluez les commandes exactes restantes pour qu'un humain puisse terminer en utilisant la skill en mode interactif.

Auto-détection de l'état de publication (mode autonome et CI)

Auto-détectez l'état de la publication à partir du calendrier et du repo. Lisez le calendrier de publication et exécutez les étapes de détection ci-dessous. En mode interactif, cette détection s'exécute également lorsque l'utilisateur fait une demande générique comme « faire la publication » sans spécifier de version ou de phase.

Étape 1 : Identifier la publication la plus récente.

# Obtenir la dernière balise de publication client
git tag -l 'client_v2.*' --sort=-version:refname | head -1

Étape 2 : Identifier la prochaine publication prévue.

Comparez la date d'aujourd'hui avec le calendrier. La prochaine publication est l'entrée prévue la plus proche dont la date proposée est >= aujourd'hui et dont la version est supérieure à la version la plus récemment publiée. Vérifiez également si une publication est en retard (date proposée < aujourd'hui mais aucune balise n'existe).

Étape 3 : Vérifier si une publication est en cours.

# Vérifier les branches release-prep pour la version suivante
git ls-remote --heads upstream 'release-prep/<NEXT_VERSION>/*'
# Vérifier la branche release
git ls-remote --heads upstream 'release/client/<NEXT_MAJOR>.<NEXT_MINOR>'
# Vérifier la balise de publication
git tag -l 'client_v<NEXT_VERSION>'
# Vérifier les PR ouvertes
gh pr list --repo microsoft/FluidFramework --search "release-prep/<NEXT_VERSION>" --state all

Étape 4 : Déterminer la phase et agir.

Présentez l'état détecté et l'action choisie à l'utilisateur (ou dans le corps du problème). Exemple :

État détecté : 2.91.0 est prévue pour 16/03/26. Aucune branche release-prep trouvée. La publication la plus récente est 2.90.0. Action : Préparation de publication mineure nécessaire pour 2.91.0 (version suivante sur main : 2.92.0).

Calendrier de publication

Le calendrier de publication se trouve dans references/release-schedule.md. Il contient les dates proposées, les versions de publication et la version « main » correspondante après chaque publication. Utilisez ceci pour déterminer les numéros de version et le timing en mode autonome.

Sélection du workflow

Demandez à l'utilisateur quelle phase il a besoin (ou détectez automatiquement en mode autonome — voir ci-dessus) :

Pour les publications de patch, allez directement à l'exécution de publication sur une branche release existante.

Étapes humaines (ne peuvent pas être automatisées)

Ces étapes nécessitent une action humaine et doivent être clairement rapportées dans les logs du workflow CI :

1. Fusionner les PR release-prep dans le bon ordre (version bump en dernier) après que CI les a créées
2. Créer la branche release (Étape 5) — nécessite des permissions élevées sur le préfixe de branche release/
3. Mettre en file d'attente le build release ADO (Étape 6) — choisir l'option « release » dans ADO
4. Annoncer la publication dans le canal Teams « General » du Fluid Framework

Key Context

• Le repo utilise pnpm comme gestionnaire de paquets
• flub est la CLI de build Fluid (pnpm flub ... ou pnpm exec flub ...)
• Schéma de version : La numérotation des versions n'est pas un motif d'incrémentation simple (ce n'est PAS toujours des multiples de 10). Lors de la suggestion d'une prochaine version, défaut à incrémenter la version mineure de 1 (par ex., 2.90.0 -> 2.91.0). Faites confiance à la version fournie par l'utilisateur sauf si elle est à plus de 7-8 versions mineures de la version actuelle (ce qui indique probablement une erreur).
• Nommage de la branche release : release/client/<major>.<minor> (par ex., release/client/2.90)
• La branche release est créée à partir du commit avant le version bump sur main
• Il n'y a pas de lerna.json dans ce repo
• Préférence de remote Git : Lors de la poussée de branches, préférez pousser vers upstream si l'un est configuré pour le repo. Vérifiez avec git remote -v en cas de doute. Fallback sur origin uniquement si aucun remote upstream n'existe. Exception : En CI (CI=true), utilisez toujours origin — il n'y a pas upstream.
• Nommage de branche de travail : N'utilisez PAS le préfixe release/ pour les branches de travail car release/ est protégé sur upstream. Utilisez la convention de nommage standard ci-dessous — ces branches doublent les marqueurs de progression.

Alternatives de commandes sûres pour CI

Certaines commandes flub nécessitent une entrée TTY interactive. En CI, utilisez ces alternatives :

Après utilisation de npm pkg set pour bumper les versions, exécutez également pnpm -r run build:genver pour mettre à jour les fichiers packageVersion.ts, et pnpm install --no-frozen-lockfile pour mettre à jour le lockfile.

Les commandes flub non-interactives qui sont sûres en CI (aucun TTY requis) : flub generate releaseNotes, flub generate changelog, flub typetests, flub release prepare.

Convention de branche de travail

Les branches de travail suivent un schéma de nommage numéroté sous release-prep/<VERSION>/ :

Exemple de publication de 2.90.0 avec version suivante 2.91.0 : release-prep/2.90.0/1-tag-asserts, release-prep/2.90.0/4-bump-2.91.0

Détection de la progression antérieure

Avant de démarrer une phase, vérifiez la progression existante en cherchant les branches et PR :

# Vérifier les branches release-prep existantes sur upstream
git ls-remote --heads upstream 'release-prep/<VERSION>/*'
# Vérifier les PR release-prep ouvertes
gh pr list --repo microsoft/FluidFramework --search "release-prep/<VERSION>" --state all

Si des branches ou des PR existent déjà, ignorez les étapes complétées et reprenez à partir du point d'arrêt.

Avant de commencer

Exécutez pnpm flub release prepare client pour vérifier la préparation. Puis vérifiez les blocages de publication :

gh issue list --repo microsoft/FluidFramework --label release-blocking --state open
gh pr list --repo microsoft/FluidFramework --label release-blocking --state open

Si l'une ou l'autre commande retourne des résultats, arrêtez et rapportez les blocages à l'utilisateur. En mode autonome, ne poursuivez pas au-delà de cette vérification s'il y a des blocages. Rappelez aussi à l'utilisateur de vérifier ADO pour les problèmes release-blocking (ne peuvent pas être interrogés via CLI).

Gestion des blocages (autonome et CI) : Si l'agent est bloqué à tout moment (blocages de publication, balise release manquante, packages npm non disponibles, erreurs de permission, ou toute autre problématique empêchant la progression), ouvrez un problème GitHub dans microsoft/FluidFramework décrivant ce qui a été complété, ce qui a échoué et l'action humaine nécessaire. Utilisez le format de titre Release <VERSION>: <brief description> et étiquetez-le avec release-blocking. Incluez les commandes exactes restantes pour qu'un humain puisse terminer en utilisant la skill en mode interactif. Puis terminez gracieusement.

Comportement par mode

Commandes (les deux modes)

Exécutez celles-ci de manière autonome dans les deux modes : policy-check:asserts, layerGeneration:gen, flub generate releaseNotes, flub generate changelog, build:genver, flub typetests, flub release prepare

Pour les bumps de version, utilisez flub bump localement ou les alternatives sûres pour CI en CI (voir Alternatives de commandes sûres pour CI).

Conventions pour les PR

Utilisez le préfixe de commit conventionnel build: pour tous les titres de PR de publication (par ex., build: tag untagged asserts for 2.90.0 release).

Points de contrôle

Mode autonome : Rapports de completion de phase

À la fin de chaque phase autonome, fournissez un résumé :

1. Ce qui a été fait — lister toutes les PR créées, branches poussées, commandes exécutées
2. Quoi faire ensuite — étapes manuelles spécifiques nécessaires (par ex., mettre en file d'attente le build ADO, fusionner les PR dans l'ordre)
3. Quand continuer — conseils de timing pour la phase suivante (par ex., « après fusion des PR » ou « demain, après mise à jour des feeds npm »)

Mode autonome : Recours aux problèmes

Si une étape en mode autonome échoue (erreurs de permission, défaillances de commandes, rejet de git push, etc.), arrêtez et ouvrez un problème GitHub dans microsoft/FluidFramework avec :

1. Ce qui a été complété — PR créées, branches poussées, commandes exécutées avec succès
2. Ce qui a échoué — l'erreur spécifique et l'étape où elle s'est produite
3. Ce qui reste — les commandes exactes pour les étapes restantes, prêtes à copier-coller
4. Comment terminer — rappeler à l'humain d'utiliser la skill fluid-release en mode interactif (claude "do the release")

Utilisez le format de titre Release <VERSION>: <brief description of failure> et étiquetez-le avec release-blocking.

Lisez le fichier de référence approprié pour la phase que l'utilisateur sélectionne, puis guidez-le étape par étape.