Résolution des dépendances entre packages Salesforce : modélisation, ordre d'installation et upgrades sûrs

Réponse courte : la résolution des dépendances entre packages, c'est la façon dont Salesforce détermine quels packages doivent déjà être présents, et dans quelles versions, avant qu'un autre puisse s'installer ou se mettre à jour. Vous la déclarez dans le tableau dependencies de sfdx-project.json, dans l'ordre d'installation. Avec le bon ordre et les bons planchers de version, les upgrades chez les abonnés sont ennuyeux. Sinon, une org se retrouve sur une version qu'elle ne peut plus quitter.

Qu'est-ce qu'une dépendance de package, exactement ?

Il y a dépendance dès que des métadonnées d'un package référencent celles d'un autre : un Flow sur un objet managé, une classe Apex qui étend une classe de base, un field set sur le champ de quelqu'un d'autre. La conséquence concrète est une précondition. Le package référencé doit être installé d'abord, dans une version au moins aussi récente que celle contre laquelle vous avez construit, faute de quoi l'installation échoue.

Comment déclarer une dépendance entre packages ?

Dans l'entrée de package directory de sfdx-project.json, sous l'une des deux formes :

• Un alias qui porte déjà la version : { "package": "[email protected]" }
• Le package et la version séparément : { "package": "MyPackage", "versionNumber": "1.0.0.RELEASED" }

Trois règles comptent plus que la syntaxe.

• L'ordre est l'ordre d'installation. Quand un package a plusieurs dépendances, la liste se lit comme la séquence dans laquelle elles doivent être installées.
• Les dépendances circulaires ne sont pas supportées. A qui dépend de B pendant que B dépend de A n'est pas une énigme à résoudre, c'est une conception à découper.
• Les chaînes à plusieurs niveaux sont supportées. C peut dépendre de B, et B de A. Avec "calculateTransitiveDependencies": true vous ne déclarez que les dépendances directes, les indirectes étant calculées. Sans cela, il faut lister chaque niveau à la main, indéfiniment.

Quels types de packages peuvent dépendre de quels autres ?

Cela contraint l'architecture : vérifiez-le avant de la dessiner.

• Un managed 2GP peut dépendre d'un managed 2GP et d'un package unlocked.
• Un managed 2GP ne peut pas dépendre d'un managed 1GP. Salesforce bloque l'installation de packages managed 2GP dans les orgs de packaging managed 1GP. Si un produit l'exige vraiment, la voie est une demande d'exception individuelle auprès du Salesforce Partner Support, pas une astuce dans un script de build.
• Un managed 1GP peut dépendre d'un managed 1GP, d'un managed 2GP et d'un package unlocked.
• Un package unlocked dépendant de packages managés est déconseillé, et rien de supporté ne dépend d'un package unmanaged.

Un package de base 1GP sous une extension 2GP est la conception de dépendance la plus fréquemment défaite trop tard, et elle coûte cher à ce stade. Lisez les combinaisons supportées avant le premier build, pas après.

Comment modéliser les packages pour garder un graphe peu profond ?

1. Une seule direction. Base, puis fonctionnalité, puis périphérie. Si deux packages veulent se référencer, les métadonnées communes appartiennent à un troisième package situe en dessous.
2. Petit et modulaire vaut mieux qu'un gros package. La création et l'installation sont plus rapides, et vous atteignez moins vite les limites.
3. La profondeur coûte, pas la largeur. Chaque niveau ajouté multiplie la coordination de release : un changement tout en bas exige une nouvelle version à chaque niveau au-dessus avant qu'un abonné n'en voie quoi que ce soit.
4. Épinglez délibérément. Un numéro de build épinglé est reproductible et ennuyeux. Un mot-clé comme RELEASED suit votre dernière version publiée, ce qui est pratique en développement et surprenant dans un build de release.

Quel est le bon ordre d'installation dans une org abonnée ?

1. Installez ou mettez à jour d'abord le package le plus bas du graphe, celui qui n'a aucune dépendance.
2. Remontez niveau par niveau, pour que chaque package trouve sa précondition satisfaite au moment de s'installer.
3. Installez en dernier le package terminal, celui que votre client a réellement acheté.
4. Vérifiez au lieu de supposer. Une requête SOQL sur SubscriberPackageVersion indique ce qui est installé dans cette org et dans quelle version, ce qui vaut mieux que de lire la page Installed Packages en espérant.

Si vous ne savez pas énoncer cet ordre de mémoire pour votre propre produit, votre équipe support ne le saura pas non plus au moment où un client est bloqué.

Comment changer une dépendance sans bloquer les abonnés ?

• La nouvelle version doit être un descendant direct de celle installée. Les abonnés ne peuvent pas sauter la lignée : un package dont l'ancestry est cassée est un package que certaines orgs ne pourront pas mettre à jour.
• Les packages bêta ne sont pas upgradables. Un abonné qui détient une bêta doit désinstaller avant d'installer une version released, ce qui en production devient une conversation sur la perte de données. Ne laissez jamais une bêta dans une org client.
• Les métadonnées retirées sont dépréciées ou supprimées lors de l'upgrade. Déplacer un composant d'un package à un autre est un retrait ici et un ajout là : l'ordre de release entre les deux constitue tout le risque.
• Relevez les planchers de version une marche à la fois. Faire bondir de plusieurs releases la version requise d'un package de base impose une chaîne de mises à jour à des abonnés qui n'en prévoyaient aucune.

La séquence qui fonctionne quand un package de base change : publiez la nouvelle version de base, amenez-y les abonnés via une version recommandée ou un push upgrade, puis publiez le package dépendant qui l'exige. Inverser ces deux étapes produit un upgrade qui échoue sur une précondition, dans une org que vous ne voyez pas et que vous ne pouvez pas réparer de votre côté.

Que faut-il automatiser ?

1. Construire le graphe depuis sfdx-project.json à chaque exécution du pipeline et faire échouer le build sur un cycle.
2. Installer toute la chaîne dans une scratch org propre, dans l'ordre déclaré, à chaque fois, pour que les erreurs d'ordre apparaissent au build et non chez un client.
3. Enregistrer les versions installées par org abonnée, pour que le support réponde à la question avant de la poser au client.

Serpent gère la résolution des dépendances entre packages, les workflows 1GP, 2GP et managed package et la gestion des versions à travers les orgs abonnées sur toutes les formules, y compris la gratuite. D'autres playbooks de packaging sont dans notre bibliothèque SF Guides.

FAQ

Un package managed 2GP peut-il dépendre d'un managed 1GP ?

Pas par défaut. Salesforce bloque la combinaison, et une exception individuelle se demande via une demande auprès du Salesforce Partner Support.

Dois-je lister les dépendances transitives ?

Seulement si vous le souhaitez. Avec "calculateTransitiveDependencies": true, vous déclarez les dépendances directes et les indirectes sont calculées. Sans cela, chaque niveau doit être listé à la main.

Que se passe-t-il si deux packages dépendent l'un de l'autre ?

Rien de bon, car les dépendances circulaires ne sont pas supportées. Extrayez les métadonnées communes dans un package inférieur dont les deux dépendent.

Quel package mettre à jour en premier dans une org abonnée ?

Le plus bas du graphe. Les dépendances passent avant les packages qui les exigent, dans l'ordre même de l'installation.

Pourquoi l'upgrade de mon client échoue-t-il avec une erreur de dépendance ?

En général un plancher de version. Le package de base installé est plus ancien que ce qu'exige votre nouvelle release : mettez d'abord le package de base à jour, puis réessayez.