CLI de Migração

Migre arquivos de configuração do Potato do formato v1 para o v2 automaticamente. Inclui um modo de simulação para visualizar todas as alterações antes de gravá-las no disco.

O Potato inclui uma ferramenta de migração para ajudar a atualizar arquivos de configuração de formatos antigos para o formato atual v2. Essa ferramenta detecta e aplica as alterações necessárias automaticamente, preservando suas configurações existentes.

Uso

bash

# Basic migration (prints migrated config to stdout)
potato migrate config.yaml --to-v2
 
# Save to a new file
potato migrate config.yaml --to-v2 --output new_config.yaml
 
# Modify the original file in place
potato migrate config.yaml --to-v2 --in-place
 
# Preview changes without applying them
potato migrate config.yaml --to-v2 --dry-run

Opções de Comando

Opção	Abreviação	Descrição
`--to-v2`		Obrigatório. Migra para o formato v2
`--output FILE`	`-o`	Grava a configuração migrada no arquivo especificado
`--in-place`	`-i`	Modifica o arquivo de configuração original diretamente
`--dry-run`		Mostra quais alterações seriam feitas sem aplicá-las
`--quiet`	`-q`	Suprime as mensagens informativas

Observação: --in-place e --output não podem ser usados juntos.

Regras de Migração

A ferramenta de migração aplica as seguintes transformações:

1. Textarea para Multiline

Converte o antigo formato textarea para o novo formato multiline em esquemas de texto.

Antes:

yaml

annotation_schemes:
  - annotation_type: "text"
    name: "feedback"
    textarea:
      on: true
      rows: 4
      cols: 50

Depois:

yaml

annotation_schemes:
  - annotation_type: "text"
    name: "feedback"
    multiline: true
    rows: 4
    cols: 50

2. Configuração de Usuário Legada

Detecta o antigo formato user_config e sugere adicionar uma configuração login explícita.

Antes:

yaml

user_config:
  allow_all_users: true

Depois:

yaml

user_config:
  allow_all_users: true
login:
  type: open

3. Formato de Requisito de Rótulo

Converte o label_requirement booleano para o formato de dicionário.

Antes:

yaml

annotation_schemes:
  - annotation_type: "multirate"
    name: "ratings"
    label_requirement: true

Depois:

yaml

annotation_schemes:
  - annotation_type: "multirate"
    name: "ratings"
    label_requirement:
      required: true

4. Sugestões de Formato de Saída

Fornece recomendações ao usar formatos de saída mais antigos. Se output_annotation_format estiver definido como csv ou tsv, sugere usar json para um suporte mais rico a dados de anotação (spans, metadados).

Exemplos

Visualizar Alterações (Simulação)

bash

$ potato migrate old_config.yaml --to-v2 --dry-run
 
Migration changes:
 
[textarea_to_multiline] Convert textarea.on to multiline format:
  - Converted textarea.on to multiline in schema 'feedback'
 
[legacy_user_config] Migrate legacy user_config to login format:
  - Added login.type: open (from allow_all_users: true)
 
Dry run - no changes written.

Migrar e Salvar em um Novo Arquivo

bash

$ potato migrate old_config.yaml --to-v2 --output migrated_config.yaml
 
Migration changes:
...
 
Wrote migrated config to migrated_config.yaml

Modo Silencioso

bash

# Just output the migrated YAML, no status messages
$ potato migrate old_config.yaml --to-v2 --quiet > new_config.yaml

Quando Usar a Migração

Considere usar a ferramenta de migração quando:

Estiver atualizando de uma versão mais antiga do Potato
Vir avisos de descontinuação ao iniciar o servidor
As opções de configuração não funcionarem como esperado
Quiser garantir que sua configuração siga as práticas recomendadas atuais

Solução de Problemas

"Configuration file is empty"

O arquivo YAML não pôde ser analisado ou está vazio. Verifique se:

O arquivo existe e pode ser lido
A sintaxe do YAML é válida
O arquivo contém conteúdo de configuração

"Invalid YAML in configuration file"

Há um erro de sintaxe no seu YAML. Problemas comuns:

Indentação incorreta
Dois-pontos ausentes após as chaves
Caracteres especiais sem aspas

Nenhuma migração necessária

Se você vir "No migrations needed - config is already up to date", sua configuração já usa o formato atual v2.

Leitura Adicional

Novidades na v2 - Visão geral das mudanças da v2
Noções Básicas de Configuração - Formato de configuração atual

Para detalhes de implementação, consulte a documentação de origem.