Niveles de estabilidad de los plugins

Los plugins de AppKit cuentan con un sistema de estabilidad de dos niveles que indica la madurez de la API y qué esperar en cuanto a cambios incompatibles.

Niveles

La ruta de importación es la principal señal de estabilidad. Importar desde /beta implica aceptar de forma explícita posibles cambios incompatibles.

Ruta de promoción

La promoción es unidireccional. Los plugins pueden entrar en cualquier nivel.

Uso

Importar plugins por nivel

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

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

Componentes de interfaz

@databricks/appkit-ui sigue el mismo patrón:

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

Comandos de la CLI

Listar plugins con su nivel de estabilidad

npx appkit plugin list

La salida incluye una columna STABILITY que muestra el nivel de cada plugin.

Crear un plugin con nivel de estabilidad

npx appkit plugin create

El flujo interactivo solicita un nivel de estabilidad (GA de forma predeterminada).

Promover un plugin

# Promover de beta a GA
npx appkit plugin promote my-plugin --to ga

# Ver los cambios sin modificar archivos
npx appkit plugin promote my-plugin --to ga --dry-run

El comando promote:

• Actualiza el campo de estabilidad en el manifest.json del plugin
• Reescribe las rutas de importación en los archivos .ts/.tsx de tu proyecto
• Ejecuta plugin sync para actualizar appkit.plugins.json

Opciones:

• --dry-run -- Muestra los cambios que se harían sin escribir nada
• --skip-imports -- Actualiza únicamente el manifiesto
• --skip-sync -- No ejecuta sync automáticamente
• --allow-installed -- Permite promover un plugin que solo existe dentro de node_modules (avanzado)

Campo del manifiesto

El campo stability de manifest.json es opcional. Si se omite, el plugin se considera GA.

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

Valores válidos: "beta", "ga".

Manifiesto de templates (appkit.plugins.json)

Cuando plugin sync detecta plugins que no son GA, incluye su nivel de estabilidad en el output. Esto se aplica a todas las rutas de descubrimiento: los plugins resueltos desde tu archivo de servidor, desde --plugins-dir o árboles de plugins locales, y desde paquetes conocidos dentro de node_modules (por ejemplo, @databricks/appkit). El nivel indicado en el manifest.json de cada plugin siempre se refleja en el manifiesto de templates sincronizado cuando no es GA.

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

Solo los plugins GA pueden marcarse como requiredByTemplate. Los plugins que no son GA siempre siguen siendo opcionales durante el init.

Para autores de plugins de terceros

La ruta de importación (/beta) solo se aplica a los plugins propios incluidos en @databricks/appkit. Los plugins de terceros declaran su estabilidad mediante el campo stability de su manifest.json. Las herramientas de la CLI (plugin list, plugin sync) muestran esta información a los usuarios.

Para autores de plugins propios (monorepo de AppKit)

Dentro del monorepo de AppKit, el campo stability del manifest.json de cada plugin es la única fuente de verdad sobre qué subruta distribuye el plugin. Dos generadores en tiempo de compilación leen todos los packages/appkit/src/plugins/<name>/manifest.json:

• tools/generate-plugin-entries.ts escribe los barriles de exportación del runtime:
  • packages/appkit/src/plugins/ga-exports.generated.ts — reexportaciones de los plugins GA, incluidas por src/index.ts (la entrada @databricks/appkit).
  • packages/appkit/src/plugins/beta-exports.generated.ts — reexportaciones de los plugins beta, incluidas por src/beta.ts (la entrada @databricks/appkit/beta).
• tools/generate-plugin-doc-banners.ts inserta (o elimina) un aviso :::warning Beta plugin al principio de la página de documentación de cada plugin (docs/docs/plugins/<name>.md), de modo que la estabilidad documentada del plugin se corresponda con su manifiesto. El script solo escribe dentro de docs/docs/plugins/: el name de cada manifiesto debe coincidir con el patrón del esquema de plugins (^[a-z][a-z0-9-]*$), y las rutas de documentación resueltas se verifican para que un name mal formado no pueda salir de ese directorio.

Todos los artefactos generados se incluyen en el repositorio y CI los verifica; un archivo desactualizado hace fallar el paso Check generated types are up to date.

El comando appkit plugin promote detecta el contexto de monorepo (la presencia de tools/generate-plugin-entries.ts) y vuelve a ejecutar el generador después de actualizar el manifiesto, de modo que las exportaciones del runtime, el appkit.plugins.json sincronizado y el manifiesto nunca puedan desincronizarse.

Para mover manualmente un plugin integrado entre niveles:

# Edita packages/appkit/src/plugins/<name>/manifest.json
# Establece "stability": "beta" (o elimina el campo para GA)
pnpm run generate:types   # regenera los tipos de schema/registry, los barriles de exportación y los avisos de la documentación
pnpm sync:template        # regenera template/appkit.plugins.json