Версионирование и changelog
### Семантическое версионирование в SWC
Экосистема SWC строится вокруг строгого семантического версионирования (SemVer), где каждая версия отражает характер изменений в кодовой базе компилятора и связанных пакетов (`@swc/core`, `@swc/cli`, `@swc/helpers`, пресеты и плагины).
Формат версии:
```
MAJOR.MINOR.PATCH
```
* **MAJOR** — изменения, нарушающие обратную совместимость
* **MINOR** — функциональные улучшения без поломки существующего поведения
* **PATCH** — исправления багов и внутренние улучшения
Особенность SWC заключается в том, что даже незначительные изменения в трансформации AST могут приводить к различиям в итоговом JavaScript-коде, поэтому семантика версий тесно связана не только с API, но и с поведением компиляции.
---
### Структура релизного цикла SWC
Релизная модель SWC включает несколько уровней артефактов:
* `@swc/core` — основной компилятор (Rust + Node bindings)
* `@swc/cli` — CLI-обёртка
* `@swc/helpers` — runtime-хелперы для трансформаций
* `@swc/plugin-*` — плагины трансформации
* пресеты (`@swc/preset-env`, `@swc/preset-typescript`)
Каждый пакет версионируется отдельно, но синхронизация релизов часто сохраняется для предотвращения несовместимости.
Ключевой принцип:
**изменение ядра компилятора не всегда требует обновления CLI, но может требовать обновления плагинов и пресетов**
---
### Changelog как основной источник совместимости
Changelog SWC представляет собой структурированный журнал изменений, в котором фиксируются:
* изменения AST трансформаций
* корректировки генерации кода
* изменения CLI параметров
* обновления конфигурационных схем
* исправления багов компиляции TypeScript и JSX
* изменения поведения плагинной системы
Типичная структура записи:
```
## x.y.z
### Features
- добавлена поддержка ...
### Bug Fixes
- исправлено поведение ...
### Breaking Changes
- изменена сигнатура ...
```
---
### Категории изменений в changelog
#### Features
Добавление новой функциональности без нарушения существующего поведения:
* новые опции трансформации (`jsc.transform.react.runtime`)
* расширение поддержки ECMAScript proposals
* улучшения производительности компиляции
* новые плагины и хуки AST
---
#### Bug Fixes
Исправления, связанные с:
* неверной трансформацией JSX
* некорректной генерацией ES5-кода
* ошибками обработки TypeScript enum/namespace
* проблемами hoisting и scope analysis
Особенность SWC — исправление может менять output code, что иногда требует повторной валидации тестов сборки.
---
#### Breaking Changes
Изменения, влияющие на совместимость:
* удаление устаревших опций конфигурации
* изменение поведения дефолтных трансформаций
* переработка plugin API
* изменение структуры AST node serialization
Пример:
* удаление поддержки `legacyDecorator: true` в пользу стандартизированного режима
* изменение поведения `module.resolver`
---
### Версионирование AST и трансформаций
SWC тесно связан с абстрактным синтаксическим деревом (AST), и изменения в нём считаются критически важными.
Ключевые аспекты:
* добавление новых типов узлов требует обновления всех трансформеров
* изменение полей node считается breaking change
* порядок traversal влияет на плагины
Пример изменения:
* было: `ClassMethod.kind = "method"`
* стало: расширенная модель с дополнительными типами `get/set/constructor`
---
### Версионирование конфигурации
Конфигурация SWC (`.swcrc`) также подчиняется SemVer-логике.
Типичные изменения:
* переименование полей
* изменение дефолтных значений
* перенос опций между секциями
Пример эволюции:
```
jsc.transform.react.runtime: "classic" | "automatic"
```
Изменение default значения может считаться minor или major в зависимости от влияния на output.
---
### CLI и версионирование поведения команд
CLI (`@swc/cli`) имеет отдельный слой стабильности:
* изменение флагов (`--config-file`, `--watch`) отражается в minor/major версиях
* изменение поведения watch-mode может считаться breaking change
* добавление новых форматов вывода (ESM/CJS) фиксируется как feature
Особенность CLI SWC заключается в том, что он лишь проксирует ядро компилятора, но сохраняет собственную стабильность интерфейса командной строки.
---
### Версионирование API @swc/core
Node.js API (`@swc/core`) является наиболее критичной частью экосистемы.
Типичные изменения:
* изменение сигнатуры `transform()`
* добавление новых опций в `TransformOptions`
* изменение структуры возвращаемого результата
Пример API:
```js
import { transform } from "@swc/core";
const output = await transform(code, {
filename: "input.ts",
jsc: {
parser: { syntax: "typescript" }
}
});
```
Изменение формы `output` (например, добавление source maps полей) фиксируется в changelog отдельно.
---
### Плагины и их версионирование
Плагинная система SWC развивается быстрее ядра и имеет собственные правила:
* плагины зависят от версии AST
* несовместимость AST = обязательный major bump
* изменение host API (Rust/JS bridge) отражается как breaking change
Типичные изменения:
* изменение интерфейса `visit_mut`
* расширение возможностей трансформации узлов
* добавление контекста компиляции
---
### Совместимость с экосистемой (Next.js, Vite, bundlers)
SWC часто используется как встроенный компилятор в других инструментах:
* Next.js использует SWC для transpilation
* bundlers интегрируют `@swc/core` как альтернативу Babel
Версионирование SWC влияет на:
* поддержку новых версий React
* обработку JSX transform runtime
* совместимость с TypeScript версией синтаксиса
Из-за этого changelog SWC часто содержит пометки:
* "affects Next.js integration"
* "may break bundler pipelines"
---
### Депрецированные возможности и жизненный цикл
SWC использует многоуровневую систему deprecation:
1. feature помечается как deprecated
2. в minor версии добавляется предупреждение
3. в следующем major — удаляется
Примеры:
* устаревшие decorators legacy mode
* старые формы module resolution
* deprecated parser flags
Важно, что deprecated функциональность может оставаться в коде несколько версий, но поведение не гарантируется.
---
### Миграции между версиями
Изменения SWC часто сопровождаются миграционными сценариями:
* обновление `.swcrc`
* замена опций трансформации
* адаптация plugin API
Типичный паттерн миграции:
* анализ breaking changes
* обновление конфигурации
* проверка output diff (AST comparison)
* корректировка зависимостей пресетов
---
### Форматирование changelog записей
Стандартная запись включает:
* краткое описание изменения
* затронутые пакеты
* тип изменения (feature/fix/breaking)
* контекст влияния (AST, CLI, API)
Пример структурированной записи:
```
- feat(core): introduce new JSX runtime transform
- fix(core): correct class field initialization order
- breaking(core): remove legacy decorators support
```
---
### Поведение minor и patch релизов
**Minor релизы**:
* расширяют AST
* добавляют новые трансформации
* сохраняют обратную совместимость
**Patch релизы**:
* исправляют генерацию кода
* оптимизируют производительность
* устраняют регрессии
Особенность SWC заключается в том, что patch может влиять на output, не меняя API, что требует осторожности при использовании в строгих билд-пайплайнах.
---
### Стабильность и предсказуемость версий
Версионная стратегия SWC направлена на баланс между:
* скоростью развития компилятора
* стабильностью output-кода
* совместимостью с JS-экосистемой
Из-за высокой частоты изменений AST и трансформаций версия SWC рассматривается не только как API-индекс, но и как маркер поведения компиляции.