Versionnement des packs
Comment les versions des packs circulent de votre dépôt au catalogue jusqu'à ce qui s'exécute réellement — règles semver, liste de contrôle des publications, épingles de version, politiques de mise à jour, détection des changements incompatibles et compatibilité SDK.
Cette page présente une vue d'ensemble du versionnement des packs : ce qu'est une version, tous les endroits où elle doit être déclarée lors d'une publication, et ce que la plateforme en fait — de la synchronisation du catalogue au moment où un workflow exécute le code de votre intégration.
Le modèle de version
Trois couches portent une version, chacune à des fins différentes :
| Couche | Déclarée dans | Rôle |
|---|---|---|
| Version du pack | pack.json → package.version, et l'index du catalogue source (scrydon.yaml → version) | Identifie une ligne du catalogue. Le catalogue conserve une ligne par (packId, version) — publier 1.2.0 ajoute une ligne ; la ligne 1.1.0 reste. |
| Version de l'entrée de contenu | pack.json → contents[].version et chaque manifeste de sous-répertoire (ex. integration-acme/manifest.json → version) | Version par type de contenu à l'intérieur du pack. Pour les intégrations, elle doit correspondre à la version compilée dans l'artefact. |
| Version de l'artefact | À l'intérieur du bundle construit (defineVendor({ version }) pour les intégrations) | Ce que la plateforme enregistre et ce que les comparaisons de mise à jour utilisent. L'installation vérifie que cela correspond à l'entrée de contenu — une discordance rejette l'installation. |
Toutes les versions sont en semver (MAJOR.MINOR.PATCH, les suffixes de pré-version comme 2.0.0-beta.1 se classent en dessous de la version finale). La plateforme compare les versions numériquement — 1.10.0 est plus récent que 1.9.0.
Les anciennes versions ne disparaissent jamais d'elles-mêmes. Les lignes du catalogue des versions précédentes restent actives (elles alimentent le rollback et la liste « Autres versions actives du catalogue »). Tout ce qui décide de ce qui est actuel — la marketplace, la page Packs, l'exécution — sélectionne la version semver la plus élevée en cours, en respectant tout épinglage de version (voir ci-dessous). Il n'est jamais nécessaire de supprimer des anciennes lignes pour qu'une nouvelle version prenne effet.
Publier une nouvelle version — la liste de contrôle
Une publication se propage uniquement lorsque chaque couche est mise à jour ensemble. En oublier une est l'erreur de publication la plus courante — en particulier l'index du catalogue : le réconciliateur de synchronisation compare les versions de l'index, donc un pack.json mis à jour derrière une entrée scrydon.yaml inchangée est silencieusement ignoré à chaque synchronisation.
Pour les intégrations : defineVendor({ version: "1.2.0" }) (ou l'équivalent de votre build), puis reconstruire l'artefact — bunx @scrydon/sdk-authoring integrations build produit dist/{vendorId}-1.2.0.bundle.tar.gz.
Le manifeste du sous-répertoire (integration-*/manifest.json → version) et l'entrée contents[] correspondante dans pack.json doivent déclarer la même version que l'artefact. L'installation vérifie l'identité de l'artefact par rapport à l'entrée du catalogue et rejette les discordances.
pack.json → package.version. Convention : la version du pack évolue au moins aussi vite que son entrée de contenu à l'évolution la plus rapide.
Pour les sources de pack Git/OCI : l'entrée scrydon.yaml de votre pack (version:) doit être mise à jour avec la nouvelle version. C'est le champ sur lequel le réconciliateur se base — sans cela, aucun des autres changements n'est jamais récupéré.
Si votre dépôt valide les sorties construites (la structure recommandée), reconstruisez dist/ et exécutez votre vérification pour que dist/ corresponde à src/. Poussez/publiez ; la plateforme synchronise la source à son intervalle (par défaut toutes les 5 minutes) ou immédiatement via Actualiser sur la source dans Paramètres → Plateforme → Packs.
Choisir le bon incrément
| Incrément | À utiliser quand | Comportement de la plateforme |
|---|---|---|
Patch (1.1.1 → 1.1.2) | Corrections de bugs, aucun changement de surface | Éligible aux politiques auto_patch et auto_minor |
Minor (1.1.x → 1.2.0) | Nouveaux outils, nouvelles entrées optionnelles, nouvelles capacités | Éligible à auto_minor |
Major (1.x → 2.0.0) | Tout ce qui est incompatible : outils supprimés/renommés, nouvelles entrées obligatoires, types d'entrée/sortie modifiés, changements de mode d'authentification | Toujours manuel ; la révision de mise à jour affiche un avertissement de rupture |
La plateforme vérifie votre choix plutôt que de lui faire confiance — voir détection des changements incompatibles.
Ce qui se passe après la publication d'une version
L'arrivée d'une nouvelle version dans le catalogue est délibérément inerte :
- La synchronisation ajoute une ligne au catalogue pour la nouvelle version (et, pour le contenu d'intégration, stocke l'artefact). Rien n'a encore changé dans ce qui s'exécute.
- Chaque intégration installée est épinglée à la version à laquelle elle a été installée. L'épingle — et non la ligne la plus récente — détermine quelle version la marketplace liste, depuis quel manifeste les outils/blocs se résolvent, et quel code s'exécute dans le sandbox.
- La nouvelle version apparaît sous la forme Mise à jour disponible sur la page Packs et sous la forme d'un badge Mise à jour sur la carte de la marketplace de l'intégration.
- L'épingle se déplace de deux façons précisément :
- Manuellement — un administrateur clique sur Mettre à jour le pack après la révision d'impact. Les exécutions de workflow en cours se terminent sur la version avec laquelle elles ont démarré ; les nouvelles exécutions utilisent la nouvelle version.
- Automatiquement — les connexions ayant opté pour une politique de mise à jour :
| Politique | Application automatique |
|---|---|
manual (par défaut) | Aucune — les mises à jour attendent la page Packs |
auto_patch | Incréments patch sans changements incompatibles détectés |
auto_minor | Incréments patch + minor sans changements incompatibles détectés |
Les incréments majeurs et toute mise à jour avec des changements incompatibles détectés attendent toujours une révision manuelle (la connexion affiche mise à jour bloquée : breaking_diff jusqu'à ce qu'un administrateur la révise).
Détection des changements incompatibles et honnêteté semver
Lorsqu'une mise à jour est disponible, la plateforme compare les manifestes installé et cible et classe les changements :
| Changement | Classification |
|---|---|
| Outil, produit ou bloc supprimé ou renommé | Incompatible |
| Nouveau champ d'entrée obligatoire ; champ existant supprimé ou type modifié | Incompatible |
| Champ de sortie supprimé ou type modifié | Incompatible |
| Mode d'authentification modifié (ex. apiKey → OAuth) | Incompatible |
| Nouvel outil/produit, nouvelle entrée optionnelle, modifications de description | Compatible |
Les résultats apparaissent dans la révision de mise à jour sur la page Packs, à côté de la liste des workflows affectés. Deux niveaux d'avertissement :
- Potentiellement incompatible (ambre) — un incrément majeur, ou des changements incompatibles correctement publiés en tant que majeur.
- Changements incompatibles dans une mise à jour non-majeure (rouge) — le diff a trouvé des changements incompatibles mais vous avez publié un minor ou patch. Les politiques de mise à jour automatique le refusent, et les administrateurs voient l'avertissement plus sévère. À éviter — republiez en tant que majeur.
Compatibilité du contrat SDK
Les artefacts d'intégration sont compilés contre une génération spécifique du contrat d'exécution plateforme↔bundle (la forme de ctx.auth, le protocole de dispatch). Le SDK estampille automatiquement cette version de contrat dans votre manifeste au moment de la build — vous ne la déclarez jamais manuellement.
- La plateforme prend en charge la génération actuelle et la précédente ; les bundles de la génération précédente sont exécutés via une traduction de compatibilité automatique.
- Un bundle construit contre une génération non prise en charge est refusé à l'installation (
integration_contract_incompatible) et à l'exécution (BUNDLE_CONTRACT_INCOMPATIBLE) avec un message indiquant les versions concernées. Les deux signifient la même chose : reconstruisez et republiez avec une version actuelle de@scrydon/sdk-authoring(un incrément patch de votre pack suffit).
Règle pratique : reconstruisez vos packs avec un SDK à jour à chaque fois que vous publiez une version, et vous ne serez jamais en retard de plus d'une génération.
Rollback
Comme les anciennes lignes du catalogue et les anciennes versions installées sont conservées, un administrateur peut faire revenir une intégration à n'importe quelle version précédente depuis la surface de gestion des versions — l'épingle recule et les exécutions en cours se vident d'abord, selon le même mécanisme qu'une mise à niveau. Un rollback ne nécessite jamais de republier quoi que ce soit de votre côté.
Exceptions par type de contenu
- Les process flows suivent toujours la dernière version active du catalogue — ils n'ont pas de version installée épinglée ni d'action de mise à jour.
- Les ontologies, domaines KB, workflows, sources de données sont versionnés par installation ; la page Packs affiche leur état d'installation par type.
Pages connexes
- Gestion des versions de pack — la présentation de l'interface d'administration (état d'installation, barre de mise à jour, révision d'impact).
- Sources de packs —
scrydon.yaml, structure Git/OCI, comportement de synchronisation, politiques de signature. - Empaqueter une intégration personnalisée dans un pack — structure du sous-répertoire et flux d'installation.