Niveaux de stabilité des plugins

Les plugins AppKit s'appuient sur un système de stabilité à deux niveaux qui indique la maturité des API et ce qu'il faut attendre en matière de changements incompatibles.

Niveaux

Le chemin d'import est le principal indicateur de stabilité. Importer depuis /beta équivaut à accepter explicitement d'éventuels changements incompatibles.

Parcours de promotion

La promotion est à sens unique. Les plugins peuvent entrer à n'importe quel niveau.

Utilisation

Importer des plugins par niveau

// Plugins GA
import { server, analytics } from "@databricks/appkit";

// Plugins bêta
import { someBetaPlugin } from "@databricks/appkit/beta";

Composants d'interface

@databricks/appkit-ui suit le même principe :

import { SomeComponent } from "@databricks/appkit-ui/react/beta";
import { someUtil } from "@databricks/appkit-ui/js/beta";

Commandes CLI

Lister les plugins avec leur niveau de stabilité

npx appkit plugin list

L'output comprend une colonne STABILITY indiquant le niveau de chaque plugin.

Créer un plugin avec un niveau de stabilité

npx appkit plugin create

Le flux interactif demande un niveau de stabilité (GA par défaut).

Promouvoir un plugin

# Promouvoir de beta vers GA
npx appkit plugin promote my-plugin --to ga

# Prévisualiser les modifications sans modifier les fichiers
npx appkit plugin promote my-plugin --to ga --dry-run

La commande promote :

• Met à jour le champ de stabilité du manifest.json du plugin
• Réécrit les chemins d'import dans les fichiers .ts/.tsx de votre projet
• Exécute plugin sync pour mettre à jour appkit.plugins.json

Options :

• --dry-run -- Affiche les modifications qui seraient appliquées, sans rien écrire
• --skip-imports -- Met uniquement à jour le manifeste
• --skip-sync -- N'exécute pas automatiquement sync
• --allow-installed -- Autorise la promotion d'un plugin présent uniquement sous node_modules (avancé)

Champ du manifeste

Le champ stability du fichier manifest.json est facultatif. S'il est absent, le plugin est considéré comme GA.

{
  "name": "my-plugin",
  "displayName": "My Plugin",
  "description": "An in-development feature",
  "stability": "beta",
  "resources": { "required": [], "optional": [] }
}

Valeurs valides : "beta", "ga".

Manifeste de modèle (appkit.plugins.json)

Lorsque plugin sync détecte des plugins non GA, il indique leur niveau de stabilité dans l'output. Cela vaut pour tous les chemins de découverte : les plugins résolus depuis votre fichier serveur, depuis --plugins-dir ou des arborescences de plugins locales, et depuis les packages connus situés sous node_modules (par exemple @databricks/appkit). Le niveau déclaré dans le manifest.json de chaque plugin est toujours repris dans le manifeste de modèle synchronisé lorsqu'il n'est pas GA.

{
  "version": "1.1",
  "plugins": {
    "my-plugin": {
      "name": "my-plugin",
      "stability": "beta",
      "package": "@databricks/appkit"
    }
  }
}

Seuls les plugins GA peuvent être marqués requiredByTemplate. Les plugins non GA restent toujours facultatifs lors de l'initialisation.

Pour les auteurs de plugins tiers

Le chemin d'import (/beta) s'applique uniquement aux plugins natifs fournis dans @databricks/appkit. Les plugins tiers déclarent leur stabilité via le champ stability de leur manifest.json. Les outils CLI (plugin list, plugin sync) exposent cette information aux utilisateurs.

Pour les auteurs de plugins internes (monorepo AppKit)

Dans le monorepo AppKit, le champ stability du manifest.json de chaque plugin constitue l'unique source de vérité pour déterminer quel sous-chemin déploie le plugin. Deux générateurs exécutés à la compilation lisent chaque packages/appkit/src/plugins/<name>/manifest.json :

• tools/generate-plugin-entries.ts génère les fichiers barils d'exports du runtime :
  • packages/appkit/src/plugins/ga-exports.generated.ts — réexports des plugins GA, inclus par src/index.ts (le point d'entrée @databricks/appkit).
  • packages/appkit/src/plugins/beta-exports.generated.ts — réexports des plugins bêta, inclus par src/beta.ts (le point d'entrée @databricks/appkit/beta).
• tools/generate-plugin-doc-banners.ts insère (ou supprime) une admonition :::warning bêta plugin en haut de la page de documentation de chaque plugin (docs/docs/plugins/<name>.md), afin que la stabilité documentée d'un plugin corresponde toujours à son manifeste. Le script n'écrit que sous docs/docs/plugins/ : le name de chaque manifeste doit respecter le motif du schéma de plugin (^[a-z][a-z0-9-]*$), et les chemins de documentation résolus sont vérifiés afin qu'un name malformé ne puisse pas sortir de ce répertoire.

Tous les artefacts générés sont commités et vérifiés par la CI ; un fichier obsolète fait échouer l'étape Check generated types are up to date.

La commande appkit plugin promote détecte le contexte monorepo (présence de tools/generate-plugin-entries.ts) et relance le générateur après la mise à jour du manifeste : les exports du runtime, le fichier appkit.plugins.json synchronisé et le manifeste ne peuvent donc jamais diverger.

Pour déplacer manuellement un plugin intégré d'un niveau à un autre :

# Modifiez packages/appkit/src/plugins/<name>/manifest.json
# Définissez "stability": "beta" (ou supprimez le champ pour la GA)
pnpm run generate:types   # régénère les types de schéma/registre, les fichiers barils d'export et les bannières de doc
pnpm sync:template        # régénère template/appkit.plugins.json