Mettre à jour les notes de version

Cette skill gère les tâches opérationnelles de maintenance des notes de version dans le repo tldraw/tldraw : ajouter de nouvelles entrées PR à next.mdx et archiver les versions quand une nouvelle version est publiée.

Cette skill s'exécute depuis le repo tldraw-internal mais opère sur un clone local de tldraw/tldraw.

Configuration

Avant de commencer, clonez le repo tldraw :

git clone https://github.com/tldraw/tldraw.git /tmp/tldraw

Tous les scripts prennent le chemin du repo comme premier argument. Exécutez les commandes de script depuis la racine du repository en remplaçant <skill-dir> par le répertoire qui contient ce SKILL.md. Tous les fichiers sont modifiés dans ce clone. À la fin, validez et poussez depuis le clone.

Cycle de version

Le SDK sort tous les quatre semaines. Une semaine avant le lancement, le SDK est gelé et une branche production est créée à partir de main. Durant la semaine de sortie, seules les correctifs d'urgence sont cherry-pickés vers production.

Les notes de version dans next.mdx doivent ultimement refléter ce qui est publié sur la branche production. Cependant, durant les ~3 semaines de développement avant le gel, nous accumulons les notes de version depuis main pour qu'elles ne soient pas vides. Le script de statut détecte dans quelle phase nous sommes en fonction de la date de la dernière version mineure :

Semaines de développement (source: "main", <3 semaines depuis la dernière version mineure) : les PRs sont collectées depuis main depuis le dernier tag de version. Ce sont des versions préliminaires — certaines peuvent ne pas être publiées si elles sont annulées ou si les cherry-picks de production diffèrent.
Semaine de gel (source: "production", 3+ semaines depuis la dernière version mineure) : les PRs sont collectées depuis la branche production en utilisant git cherry par rapport à la branche de version précédente. Seules les PRs qui ont atterri avant le gel ou qui ont été corrigées en urgence sur production sont incluses. Les entrées accumulées depuis main qui ne sont pas sur production seront supprimées.

Processus

1. Vérifier le statut

Exécutez le script de statut pour déterminer les versions et la branche de diff :

<skill-dir>/scripts/get-changelog-status.sh /tmp/tldraw

Cela retourne :

source - soit "main" (semaines de développement) soit "production" (semaine de sortie)
diff_branch (par exemple, v4.3.x) - la branche à comparer (utilisée quand source est "production")
last_tag (par exemple, v4.4.0) - le dernier tag de version (utilisé quand source est "main")
latest_release - la version la plus récemment publiée
Si l'archivage est nécessaire

2. Gérer l'archivage (si nécessaire)

Si une nouvelle version a été publiée depuis last_version dans next.mdx :

Copiez le contenu de next.mdx vers vX.Y.0.mdx (par exemple, v4.3.0.mdx)
Mettez à jour le frontmatter dans le nouveau fichier :
- Définissez title à la version
- Mettez à jour les dates
- Ajoutez le lien de la version GitHub après le frontmatter
Ajoutez la nouvelle version à l'index des versions dans apps/docs/content/getting-started/releases.mdx :
- Ajoutez une ligne en haut de la section ## v{major}.x appropriée
- Format : - [vX.Y](/releases/vX.Y.0) - Brève description
- La description doit être un court résumé des points clés de la version à partir du paragraphe d'introduction (3-5 fonctionnalités clés, séparées par des virgules)
- Si une nouvelle section de version majeure est nécessaire, créez-la au-dessus de la précédente
Réinitialisez next.mdx :
- Mettez à jour le champ last_version à la nouvelle version
- Videz les sections de contenu
- Conservez la structure du fichier pour accumuler les nouveaux changements

3. Trouver les nouvelles PRs

L'approche dépend du champ source de l'étape 1.

Si source est "production" (semaine de sortie) :

Obtenez les numéros de PR sur la branche production depuis la version précédente :

<skill-dir>/scripts/get-new-prs.sh /tmp/tldraw <diff_branch>

Cela utilise git cherry (même approche que extract-draft-changelog.tsx) pour comparer les patches entre origin/production et origin/<diff_branch>. Contrairement à git log, git cherry gère correctement les commits cherry-pickés en comparant le contenu des patches plutôt que les hachages de commits.

Si source est "main" (semaines de développement) :

Obtenez les numéros de PR sur main depuis le dernier tag de version :

<skill-dir>/scripts/get-new-prs-from-main.sh /tmp/tldraw <last_tag>

Cela utilise git cherry pour comparer les patches entre origin/main et le tag de version, en excluant les commits qui ont été cherry-pickés vers production et déjà publiés dans la version.

Les deux scripts produisent :

stdout : numéros de PR (un par ligne) extraits des messages de commit
stderr : commits sans numéro de PR (généralement des correctifs d'urgence ou des commits directs)

4. Résoudre les commits hotfix

Vérifiez stderr de l'étape 3 pour tout commit [HOTFIX] sans numéro de PR. Pour chacun pertinent pour le SDK (ignorez ceux dotcom uniquement), trouvez la PR correspondante :

gh pr list -R tldraw/tldraw --state merged --search "<mots-clés du titre hotfix>" --json number,title --jq '.[]'

Vérifiez aussi les PRs étiquetées sdk-hotfix-please, mais vérifiez qu'elles ont réellement atterri sur production — ce label est aussi utilisé pour les patch releases sur la branche de version précédente (par exemple, v4.3.x) :

gh pr list -R tldraw/tldraw --label "sdk-hotfix-please" --state merged --limit 20 --json number,title,mergedAt

Ajoutez tout numéro de PR correspondant à la liste des PRs production de l'étape 3.

5. Récupérer les détails des PRs

Récupérez en lot toutes les informations des PRs :

<skill-dir>/scripts/fetch-pr-batch.sh <pr1> <pr2> ...

6. Supprimer les entrées obsolètes

Comparez la liste complète des PRs (étapes 3 + 4) par rapport aux numéros de PR déjà référencés dans next.mdx. Supprimez toute entrée de next.mdx dont la PR n'est pas dans l'ensemble actuel.

Quand source est "production" : Cela supprime les entrées qui ont été accumulées depuis main lors du développement mais qui ne sont pas arrivées en production. Ce sont des PRs qui ont atterri sur main après la création de la branche production et qui ne seront pas publiées dans cette version.
Quand source est "main" : Cela supprime les entrées des PRs qui ont été annulées ou qui ne sont plus sur main. La suppression est moins agressive car l'ensemble complet n'est pas finalisé jusqu'à ce que production soit gelée.

Lors de la suppression d'une entrée, vérifiez aussi si elle a été référencée dans une section en vedette « Ce qui est nouveau » et supprimez cette section aussi. Mettez à jour le paragraphe d'introduction s'il mentionne une fonctionnalité supprimée.

7. Ajouter les nouvelles entrées

Pour chaque PR qui ne figure pas déjà dans next.mdx :

Vérifiez les labels et le corps de la PR par rapport aux règles de catégorisation du guide de style
Ignorez les PRs qui doivent être omises (voir guide de style)
Ignorez les PRs qui corrigent des bugs introduits dans le même cycle de version (c'est-à-dire des bugs causés par d'autres PRs déjà dans next.mdx qui n'étaient pas dans la version précédente)
Si une PR est une annulation, supprimez aussi l'entrée de la PR originale annulée de next.mdx si elle y figure
Ajoutez les entrées à la section appropriée
Promouvoir les changements significatifs vers des sections en vedette quand justifié

8. Vérifier

Vérifiez que :

Chaque PR référencée dans next.mdx est dans l'ensemble actuel des PRs (depuis main ou production selon source)
Les liens des PRs sont corrects
Les contributeurs communautaires sont crédités
Les sections sont dans le bon ordre
Les breaking changes sont marqués avec 💥
Les dépréciations sont marquées avec 🔜

Note : Quand source est "main", les entrées sont préliminaires. Certaines peuvent être supprimées plus tard quand la branche production est gelée et la source bascule vers "production".

9. Pousser les changements

Après avoir édité next.mdx (et tout fichier d'archive), validez et poussez depuis le clone tldraw :

cd /tmp/tldraw
BRANCH="update-release-notes-$(date -u +%Y%m%d-%H%M)"
git checkout -b "$BRANCH"
git add apps/docs/content/releases/
git commit -m "docs: update release notes"
git push -u origin "$BRANCH"

Puis créez la PR en utilisant le workflow ../pr/SKILL.md et les standards dans ../write-pr/SKILL.md :

Titre : docs(releases): update release notes
Type de changement : other
Plan de test : Supprimez la liste numérotée (pas d'étapes de test manuel). Décochez les deux options unit tests et end to end tests.
Notes de version : Omettez cette section (travail sur la documentation interne sans impact utilisateur)
Paragraphe de description : Commencez par « In order to... » et mentionnez la source (main ou production) et ce qui a été mis à jour (nouvelles entrées ajoutées, entrées obsolètes supprimées, archivage effectué, etc.)
Incluez un tableau Code changes avec une ligne Documentation

Le champ `last_version`

Le frontmatter de next.mdx inclut un champ last_version qui suit la version la plus récemment publiée. Cela détermine quelles PRs sont « nouvelles » et doivent être ajoutées.

Workflow de version du SDK

Lors d'une version du SDK, cette skill est exécutée deux fois pour mettre le site docs dans son état post-version :

Premier passage — mettez à jour next.mdx avec toutes les PRs qui seront publiées dans la version (source est "production" durant la semaine de gel). Cela garantit que les notes de version sont complètes avant la publication.
Publiez la version sur NPM — cela se fait en dehors de cette skill.
Deuxième passage — maintenant que la version est publiée, le script de statut détectera needs_archive: true. Ce passage :
- Archive next.mdx vers un fichier versionné (par exemple, v4.5.0.mdx)
- Ajoute la nouvelle version à l'index des versions (releases.mdx)
- Réinitialise next.mdx avec le nouveau last_version
- Trouve les PRs qui ont atterri sur main durant le gel (depuis le tag de version) et les ajoute au nouveau next.mdx

Après le deuxième passage, le site docs reflète la version publiée et next.mdx a déjà une longueur d'avance sur les changements du prochain cycle.

Références

Guide de style : Voir shared/release-notes-guide.md pour des conseils sur ce que doit contenir et comment formater un article de notes de version.
Guide de rédaction : Voir shared/writing-guide.md pour les conventions de voix et de style.
Scripts : Voir scripts/ pour les helpers d'automatisation