major-version-mode

Contexte

Cette tâche fait partie de la prochaine version majeure du AI SDK. Les changements qui cassent la compatibilité sont acceptables.

Directives pour les changements qui cassent la compatibilité

Bien que les changements qui cassent la compatibilité soient acceptables, il est toujours encouragé de minimiser les perturbations inutiles pour les consommateurs tiers du AI SDK. Fournir des alias dépréciés et une logique de migration automatisée peut faciliter la transition.

Exports renommés/modifiés

Si vous renommez ou modifiez une fonction ou un type exporté, fournissez un alias déprécié comme export au niveau du package dans la mesure du possible :

/** @deprecated Use `newFunctionName` instead. */
export { newFunctionName as oldFunctionName } from './new-module';

Faites cela seulement si cela n'introduit pas de dette technique significative. Si c'est le cas, ignorez l'alias — mais consultez l'utilisateur d'abord avant de faire une rupture complète.

Types de messages modifiés (par ex. dans @ai-sdk/provider-utils)

Si vous modifiez les formes de messages du modèle (par ex. les types de parties de contenu dans packages/provider-utils/src/types/content-part.ts) :

1. Dépréciez dans @ai-sdk/provider-utils plutôt que de supprimer immédiatement, si possible. Marquez les types/membres dépréciés avec un commentaire JSDoc @deprecated et une note TODO pour suppression dans la version majeure suivante.
2. Conservez les équivalents dépréciés dans packages/ai/src/prompt/content-part.ts — ce fichier est la couche orientée consommateur et doit conserver les anciennes formes dans les schémas Zod afin que le code consommateur existant continue de compiler avec un avertissement de dépréciation. Incluez une note similaire concernant la dépréciation et la suppression dans la version majeure suivante.
3. Si la dépréciation propre n'est pas réalisable sans dette technique significative, une suppression complète peut être préférable — mais consultez l'utilisateur d'abord.

Changements de spécification du fournisseur (@ai-sdk/provider)

Le package provider définit la spécification que les implémenteurs de fournisseurs codent par rapport à. Il ne doit généralement pas être modifié en dehors des versions majeures, donc maintenir la spécification propre et cohérente est critique.

Les changements qui cassent la compatibilité sans maintenir des mesures temporaires de rétrocompatibilité sont plus acceptables ici qu'ailleurs, car l'audience est plus petite — bien moins de développeurs implémentent leurs propres fournisseurs que construisent des fonctionnalités par-dessus le AI SDK.

Règles :

• Modifiez uniquement la dernière version de spécification. Les anciennes interfaces de spécification versionnées doivent rester complètement intactes.
• Les alias dépréciés ne sont pas requis — une rupture complète est préférable pour préserver la clarté de la spécification.
• La version de spécification actuelle n'est pas identique au numéro de version majeure actuel du AI SDK. Si ce n'est pas clair sur quelle version de spécification opérer, consultez l'utilisateur avant de procéder.

Documentation

Après avoir implémenté les changements, mettez à jour la documentation pertinente dans content/docs/.

Si le changement nécessite que les consommateurs mettent à jour leur code ou migrent des données stockées, ajoutez une section au dernier guide de migration :

• Trouvez le guide de migration avec le numéro de version le plus élevé dans content/docs/08-migration-guides/
• Ajoutez une section concise expliquant ce qui a changé et comment migrer