Compatibilité : ce que promet une version
Une mise à niveau d’Aggrega peut modifier plusieurs surfaces sur lesquelles vous vous appuyez : les schémas selon lesquels vos documents sont écrits, les commandes et les options que vos scripts appellent, les outils qu’un assistant d’IA appelle, les codes d’erreur que vous consignez et les kits de plugin avec lesquels un plugin est construit. Cette page indique, pour chacune d’elles, ce qu’une version peut modifier et ce qu’elle ne modifie pas. Une surface que cette page ne nomme pas ne porte aucune promesse au-delà de ce qu’indique sa propre page de référence. La dernière section indique où une version vous signale que l’une d’elles a changé. Les promesses de cette page s’appliquent à partir de la version 0.9.0. Les Releases antérieures à la version 0.9.0 ne sont pas prises en charge : le registre du hub, hub.aggrega.ai, ne fournit aucune version de Plugin conçue pour elles, et leurs compilateurs ne peuvent pas lire le catalogue de ce registre, dont les documents déclarent aggrega.ai/v1beta1.
Aggrega est publié sous forme de versions 0.x.y : une version corrective incrémente le dernier nombre, une version mineure celui du milieu. La propre metadata.version d’une entité de catalogue est une autre question — son auteur la choisit, selon les critères d’incrément de version que vérifie aggrega lint --pre-publish, et Résolution des versions décrit comment une référence en sélectionne une.
Schémas
Chaque schéma publié par Aggrega appartient à une version d’API, aggrega.ai/v1beta1 — la valeur qu’un document d’entité déclare dans son apiVersion. La règle ci-dessous s’applique à chacun d’eux : les types d’entité, les charges utiles des plugins, ainsi que les schémas de l’espace de travail et les autres — l’IR, la configuration de l’espace de travail, les fichiers de verrouillage et le reste —, tous répertoriés dans la Référence des schémas. La version d’API est indépendante du numéro de version : de nombreuses versions lisent la même version d’API.
Ce qui peut changer au sein de v1beta1
Au sein d’une version d’API, un schéma ne change que de manière additive, comme Kubernetes fait évoluer ses propres versions d’API. Une version peut :
- modifier une description ;
- ajouter un champ, lorsque ce champ est facultatif.
Tout document valide avant une telle modification reste valide après celle-ci et conserve la même signification. Un programme qui lit un document écrit par le compilateur, comme l’IR ou un fichier de verrouillage, doit accepter un champ qu’il ne connaît pas, car un champ facultatif ajouté peut apparaître dans cette sortie au sein de v1beta1.
Ce qui nécessite v1beta2
Chacune de ces modifications nécessite une nouvelle version d’API, aggrega.ai/v1beta2 :
- supprimer ou renommer un champ ;
- rendre un champ obligatoire ;
- restreindre un type, ou l’ensemble des valeurs qu’un champ accepte ;
- changer ce que signifie une valeur.
Une nouvelle version d’API est un changement incompatible, planifié et annoncé comme tel dans la version qui l’apporte.
Un nouveau champ facultatif arrive dans un catalogue avec le compilateur qui le connaît
Le compilateur refuse un champ que son schéma ne déclare pas. C’est cette rigueur qui intercepte une clé mal orthographiée, et elle a une conséquence qu’un lecteur ne devinerait pas : une entité de catalogue ne peut commencer à utiliser un champ facultatif nouvellement ajouté que dans une version qui livre un compilateur connaissant ce champ.
Par exemple, supposons qu’une version ajoute un champ facultatif au schéma du Component — appelons-le spec.newField :
- Chaque Component écrit avant cette version reste valide ; aucun d’eux ne définit ce champ.
- Un auteur de catalogue publie une nouvelle version d’un Component qui définit
spec.newField. - Un compilateur de cette version, ou d’une version ultérieure, valide et construit le Component.
- Un compilateur d’une version antérieure le refuse, car son propre schéma ne déclare pas le champ : la validation signale
spec.newField: unexpected propertyet indique la ligne.
Ainsi, quiconque construit sur cette version du catalogue passe d’abord à la version qui a ajouté le champ, et un catalogue ne publie une entité utilisant ce champ qu’une fois cette version sortie. La manière dont une Release verrouillée conserve les versions qu’elle a résolues est décrite dans Résolution des versions.
La ligne de commande et les outils de l’assistant
Les scripts, les pipelines de CI et les configurations d’assistant appellent par leur nom les commandes aggrega, les options et les outils de l’assistant. Dans les versions 0.x :
- Une version corrective ne supprime ni ne renomme jamais une commande, une option ou un outil de l’assistant.
- Une version mineure peut en supprimer ou en renommer un, et son journal des modifications l’indique sous Removed ou Changed.
- Les ajouts — une nouvelle commande, une nouvelle option ou un nouvel outil — peuvent arriver dans n’importe quelle version.
Les outils de l’assistant sont les outils que aggrega mcp propose à un assistant connecté. La réponse du serveur lui-même en donne la liste complète, et Ce que votre assistant peut faire avec Aggrega explique comment la demander. Un outil qui exécute une commande tire son nom du chemin d’invocation de la commande, de sorte que renommer une commande renomme son outil. La Vue d’ensemble de la CLI répertorie toutes les commandes.
Codes d’erreur
Chaque condition d’arrêt porte un code court — la lettre E et quatre chiffres, comme dans [DEVELOPER_ERROR E0007] — affiché en tête de son diagnostic. Les codes courts sont un contrat public : un code est attribué une seule fois, n’est jamais renuméroté et n’est jamais donné à une autre condition. Le code d’une condition retirée reste retiré, de sorte qu’un code consigné dans un runbook, une règle de CI ou un ticket désigne la même condition après chaque mise à niveau.
Sentinelles d’erreur présente les identifiants que porte une condition — le code court qu’une personne cite, le code descriptif qu’un programme consigne et l’accesseur Go auquel un programme compare —, ce que chacun promet et comment on évite qu’un numéro retiré soit attribué à nouveau. Son tableau de toutes les conditions résout chaque code court, y compris les codes retirés, et aggrega explain en résout un dans le terminal.
Kits de Plugin
Les kits de développement de plugins — github.com/aggrega-ai/aggrega-pdk/go, aggrega-pdk-rust et @aggrega-ai/aggrega-pdk-typescript — ainsi que les codecs aggrega-abi qu’ils réexportent suivent le versionnage sémantique à partir de 0.9.0. Les trois langages des kits partagent un même numéro de version, et les trois langages des codecs en partagent un autre.
- Un plugin construit avec une version continue de se construire avec toutes les versions ultérieures de la même ligne. Au sein de
0.9.x, une version peut ajouter des fonctions, des types et des constantes exportés, et n’en supprime ni n’en modifie jamais aucun. - Un changement incompatible d’une API exportée n’est livré que dans une nouvelle version mineure (de
0.9.xà0.10.0), et une version corrective ne casse jamais la compatibilité. Les kits et les codecs passent à1.0.0en même temps que la1.0.0d’Aggrega elle-même, après quoi un changement incompatible incrémente le numéro majeur. - Un changement incompatible dans les codecs est un changement incompatible dans les kits, qui incrémentent avec lui leur propre version mineure, car ils réexportent les types des codecs.
- Le fait qu’un champ ou un membre ajouté à un type existant compte comme un ajout dépend du langage. Le README de chaque kit, publié avec le paquet, décrit le cas de son langage sous « Compatibility ».
Cette promesse couvre l’API que nomme le code source d’un plugin. Ce qui transite entre le compilateur et un plugin en cours d’exécution relève plutôt de la version d’ABI des plugins : au sein d’une version d’ABI, un socket ne gagne que des descriptions et des champs facultatifs, de sorte qu’un plugin construit avec elle continue de se charger. Le contrat des plugins décrit les sockets, et le guide du développeur de plugins le flux de travail qui les entoure.
Ce que dit le journal des modifications d’une version
Les notes de chaque version, sur la page des versions, contiennent son journal des modifications, regroupé sous des titres tels que Added, Changed, Removed et Fixed. Pour les surfaces de cette page :
- Une commande, une option ou un outil de l’assistant supprimé ou renommé est répertorié sous Removed ou Changed, dans la version mineure qui effectue le changement.
- Une nouvelle version d’API de schéma est annoncée comme changement incompatible dans la version qui l’apporte.
- Un changement incompatible des kits de plugin ou des codecs se voit dans leur numéro de version : il s’agit d’une nouvelle version mineure inférieure à
1.0.0. - Un code d’erreur ne change jamais de signification, aucune version n’a donc à en annoncer un.