Старые материалы показывают происхождение языка, но не обещают совместимость. Сохраняйте задуманное поведение, переписывайте исходный код в текущей грамматике и позволяйте средству проверки явно выявить нерешённые границы. Совместимые изменения версии продукта не требуют отдельного руководства по миграции.
1. Инвентаризация до переписывания
Запишите входные файлы, корни модулей, входные и выходные данные, ошибки, внешние эффекты и эталонные протоколы. Отделите настоящий Topaz от примеров на Rust, JavaScript или коде фреймворка. Не выводите семантику из старой страницы; используйте текущую спецификацию и канонические примеры.
2. Нормализация повторяющихся форм
mut let→let mut,[T]→Array<T>, старое обозначение типа функции →(T) -> U.- Остаток шаблона списка —
..rest, вариативный параметр —...args: T, анонимная функция — лямбда, получатель — только разрешённыйself. - Индексация строки и
.lengthзаменяются скалярными API; шаблоны используют зарегистрированные теги и{expr}. - Восстанавливаемая ошибка представляется через
Result, отсутствие значения — черезOptionили допускающийnullтип, ошибка выполнения остаётся явной, а очистка выполняется черезdeferили разрешённыйusing. - Модули переписываются в текущие формы
importиexport; синтаксис других языков остаётся на явно отмеченной границе сборки или конвертации.
3. Исторический код остаётся историческим
Старое написание помещается в блок text, а не в канонический блок Topaz:
mut let names: [string] = ["Ada"]
let first = names[0]Текущая форма явно показывает изменяемость, тип коллекции и безопасную проверку границ:
let mut names: Array<string> = ["Ada"]
let first: Option<string> = names.get(0)
print("{first}")4. Восстановление доказательств, а не только разбора
Запустите topaz check, затем эталонные сценарии через run. Собирайте только нужные цели и сравнивайте заранее определённые наблюдаемые результаты. Повторно проверьте инициализацию модулей, порядок, скалярные позиции строк, ошибки, очистку и профили среды. Успешный разбор сам по себе не доказывает сохранение поведения.
5. Граница автоматизации
Команда миграции охватывает только явно поддерживаемые переходы исходного кода и пакетов, а не произвольное преобразование семантики. Подробные руководства могут содержать API фреймворков и синтаксис других языков, которые нельзя проверить автоматической заменой. Сравните пример в Классике, затем адаптируйте его к текущему языку.
Условие завершения
Миграция завершена, когда текущая проверка проходит, ожидаемые результаты записаны заново, допущенные бэкенды согласуются на заявленных тестах, канонические блоки кода не содержат запрещённых форм, текущие ссылки заменили устаревшие источники, а каждое неподдерживаемое поведение отклоняется явно.