Níveis de estabilidade de plugins

Os plugins do AppKit contam com um sistema de estabilidade de dois níveis que indica a maturidade da API e o que esperar em relação a mudanças incompatíveis.

Níveis

O caminho de importação é o principal sinal de estabilidade. Importar de /beta significa consentir explicitamente com possíveis mudanças incompatíveis.

Caminho de promoção

A promoção é unidirecional. Os plugins podem entrar em qualquer nível.

Uso

Importando plugins por nível

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

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

Componentes de UI

@databricks/appkit-ui segue o mesmo padrão:

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

Comandos da CLI

Listar plugins com estabilidade

npx appkit plugin list

A saída inclui uma coluna STABILITY que mostra o nível de cada plugin.

Criando um plugin com estabilidade

npx appkit plugin create

O fluxo interativo solicita um nível de estabilidade (o padrão é GA).

Promover um plugin

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

# Visualizar as alterações sem modificar os arquivos
npx appkit plugin promote my-plugin --to ga --dry-run

O comando promote:

• Atualiza o campo de estabilidade no manifest.json do plugin
• Reescreve os caminhos de importação nos arquivos .ts/.tsx do seu projeto
• Executa plugin sync para atualizar o appkit.plugins.json

Opções:

• --dry-run -- Mostra o que seria alterado sem gravar nada
• --skip-imports -- Atualiza apenas o manifesto
• --skip-sync -- Não executa o sync automaticamente
• --allow-installed -- Permite promover um plugin que existe apenas em node_modules (avançado)

Campo do manifesto

O campo stability em manifest.json é opcional. Quando ausente, o plugin é considerado GA.

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

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

Manifesto de Template (appkit.plugins.json)

Quando o plugin sync encontra plugins que não são GA, ele inclui a estabilidade deles na saída. Isso vale para todos os caminhos de descoberta: plugins resolvidos a partir do seu arquivo de servidor, de --plugins-dir / árvores de plugins locais e de pacotes conhecidos em node_modules (por exemplo, @databricks/appkit). O nível definido no manifest.json de cada plugin sempre é refletido no manifesto de template sincronizado quando não for GA.

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

Somente plugins GA podem ser marcados como requiredByTemplate. Plugins que não são GA permanecem sempre opcionais durante o init.

Para autores de plugins de terceiros

O caminho de importação (/beta) se aplica apenas aos plugins de primeira parte distribuídos dentro do @databricks/appkit. Plugins de terceiros declaram a estabilidade por meio do campo stability em seu manifest.json. As ferramentas de CLI (plugin list, plugin sync) apresentam essa informação aos usuários.

Para autores de plugins de primeira parte (monorepo do AppKit)

No monorepo do AppKit, o campo stability do manifest.json de cada plugin é a única fonte de verdade sobre qual subcaminho distribui o plugin. Dois geradores executados em tempo de build leem cada packages/appkit/src/plugins/<name>/manifest.json:

• tools/generate-plugin-entries.ts gera os barris de exportação de runtime:
  • packages/appkit/src/plugins/ga-exports.generated.ts — reexportações dos plugins GA, incluídas por src/index.ts (o ponto de entrada @databricks/appkit).
  • packages/appkit/src/plugins/beta-exports.generated.ts — reexportações dos plugins beta, incluídas por src/beta.ts (o ponto de entrada @databricks/appkit/beta).
• tools/generate-plugin-doc-banners.ts insere (ou remove) um aviso :::warning Beta plugin no topo da página de documentação de cada plugin (docs/docs/plugins/<name>.md), para que a estabilidade documentada de um plugin acompanhe seu manifesto. O script só escreve dentro de docs/docs/plugins/: cada name do manifesto deve corresponder ao padrão do esquema de plugin (^[a-z][a-z0-9-]*$), e os caminhos de documentação resolvidos são verificados para que um name malformado não consiga sair desse diretório.

Todos os artefatos gerados são versionados no repositório e verificados pelo CI; um arquivo desatualizado faz a etapa Check generated types are up to date falhar.

O comando appkit plugin promote detecta o contexto de monorepo (pela presença de tools/generate-plugin-entries.ts) e executa o gerador novamente após atualizar o manifesto, de modo que as exportações de runtime, o appkit.plugins.json sincronizado e o manifesto nunca fiquem fora de sincronia.

Para mover um plugin integrado entre níveis manualmente:

# Edite packages/appkit/src/plugins/<name>/manifest.json
# Defina "stability": "beta" (ou remova o campo para GA)
pnpm run generate:types   # regenera os tipos de schema/registry, os barrels de exportação e os banners da documentação
pnpm sync:template        # regenera template/appkit.plugins.json