Skip to content
PПромтбук
RUEN
Главная/Код/Документация
04Документация

Changelog и версионирование

Keep a Changelog + SemVer: что писать, когда бампать, как объявлять breaking.

Настрой changelog и версионирование.

SemVer (MAJOR.MINOR.PATCH)

Что изменилосьБамп
Breaking API change (clients ломаются)MAJOR
Новая функциональность, обратно совместимаяMINOR
Bugfix, обратно совместимыйPATCH
Pre-release-alpha.1, -beta.2, -rc.1

Что считается breaking

  • Удалить или переименовать публичный экспорт
  • Изменить сигнатуру функции (добавить required параметр, изменить тип)
  • Изменить поведение по умолчанию
  • Изменить формат вывода
  • Удалить deprecated API
  • Не breaking: новые опциональные параметры с default, новые экспорты, fix очевидных багов

Format: Keep a Changelog

# Changelog

Все значимые изменения этого проекта документируются в этом файле.

Формат основан на [Keep a Changelog](https://keepachangelog.com),
проект следует [Semantic Versioning](https://semver.org).

## [Unreleased]

### Added
- ...

### Changed
- ...

### Deprecated
- ...

### Removed
- ...

### Fixed
- ...

### Security
- ...

## [1.2.0] - 2025-04-15

### Added
- Поддержка SAML SSO ([#123](link))
- Новый endpoint `GET /api/users/me`

### Changed
- Дефолтный page size с 50 на 25

### Fixed
- Race condition при concurrent updates ([#145](link))

## [1.1.1] - 2025-04-01
...

Категории (Keep a Changelog)

  • Added — новые функции
  • Changed — изменения в существующем поведении (но не breaking)
  • Deprecated — будет удалено в следующих версиях
  • Removed — удалено в этой версии (breaking!)
  • Fixed — исправления багов
  • Security — патчи безопасности

Как писать строки

✓ Хорошо:

  • "Added --no-cache flag to build command"
  • "Fixed crash when user has > 1000 projects"
  • "Removed legacy_api parameter (was deprecated since 1.5)"

✗ Плохо:

  • "Various improvements"
  • "Bug fixes"
  • "Refactored code" (это для разработчика, не для пользователя)

От лица пользователя, не разработчика. "Refactored auth module" → "Login is now 2x faster".

Deprecation процесс

  1. Объяви в MINOR релизе:

    • Лог-варн в runtime ("X is deprecated, use Y. Will be removed in v3.0")
    • Документация — пометить как deprecated
    • Changelog → Deprecated

  2. Подожди минимум 1 MAJOR версию (лучше 2)

  3. Удали в MAJOR релизе:

    • Changelog → Removed
    • Migration guide

Объявление breaking changes

Каждый MAJOR должен иметь:

  • Migration guide — что менять в коде клиента
  • Why — почему пошли на breaking change
  • Список всех breaking в одном месте
# Migration: 1.x → 2.0

## Breaking changes

### `getUser()` теперь async

**Было:**
```ts
const user = getUser(id);

Стало:

const user = await getUser(id);

Почему: ...

Удалён legacy_api параметр

...


## Автоматизация

- **commit messages → changelog**: используй [Conventional Commits](https://conventionalcommits.org)
  - `feat: ...` → Added
  - `fix: ...` → Fixed
  - `BREAKING CHANGE: ...` → Major bump
- **Tools:** changesets, semantic-release, release-please

## Release process

1. Открывается `[Unreleased]` секция, пишутся изменения по PR
2. Перед релизом: `[Unreleased]` → `[X.Y.Z] - YYYY-MM-DD`
3. Создаётся новый `[Unreleased]` сверху
4. Тег в git: `vX.Y.Z`
5. GitHub Release с содержимым changelog

## Анти-паттерны

- ❌ Changelog с одной строкой "Updates" в каждом релизе
- ❌ Бамп MAJOR версии без changelog
- ❌ Удаление функционала в PATCH
- ❌ Не объявлены deprecation — выкидываешь и ломаешь клиентов
- ❌ Versions: `v2.0.0-final-FINAL-USE-THIS-ONE` (ага)

## В конце
- CHANGELOG.md шаблон
- VERSION_STRATEGY.md (если нетривиальная)
- Конфиг автоматизации (если используешь)
К подразделу «Документация»
Похожие промты
design / design-system

Процесс депрекации компонента

Пометить deprecated (badge, console warn, types), дать миграцию (codemod, before/after), удалить. Версии, support window, коммуникация.

design-systemdeprecationmigration
Продвинутый1-2 часа
agents / prompt-engineering

Версионирование промтов через git

Структура репо для prompt templates, ревью изменений, deploy в рантайм, мгновенный rollback при регрессии.

prompt-engineeringversioninggit
Средний30-60 мин
agents / tools

Публикация MCP-сервера: npm-layout, README, semver, deprecation

Готовый план релиза MCP-сервера в npm: структура пакета (bin/dist/types), claude_desktop_config snippet, README essentials, semver и стратегия deprecation.

mcptoolspublishing
Средний1-2 часа