Semantic versioning и автоматический changelog
1
# Semantic versioning и автоматический changelog
Версионирование — это не просто цифры в package.json. Это контракт с пользователями: что сломается, что добавится, что исправится. Когда проект растёт, ручное ведение версий и changelog превращается в рутину, где легко ошибиться.
Я перевёл несколько проектов на автоматическое версионирование. Расскажу, как это работает и какие инструменты использовать.
## Введение в semver (major.minor.patch)
Semantic versioning (semver) — стандарт версионирования вида `MAJOR.MINOR.PATCH`:
- **MAJOR** (1.0.0 → 2.0.0) — breaking changes. API изменился несовместимо.
- **MINOR** (1.0.0 → 1.1.0) — новая функциональность, обратно совместимая.
- **PATCH** (1.0.0 → 1.0.1) — исправления багов.
Примеры: удалили метод → major, добавили опциональный параметр → minor, исправили баг → patch.
До версии 1.0.0 проект нестабилен, breaking changes допустимы в minor.
## Conventional commits: формат и зачем нужен
Conventional commits — стандарт формата коммитов для автоматического определения типа изменения.
Формат:
```
():
```
Типы:
- `feat:` — новая функциональность (→ minor).
- `fix:` — исправление бага (→ patch).
- `BREAKING CHANGE:` в footer или `!` после типа (→ major).
- `docs:`, `refactor:`, `test:`, `chore:` — не влияют на версию.
Примеры:
```
feat(auth): add OAuth2 support
fix(api): handle null response in getUser
feat!: remove deprecated login method
```
Зачем: автоопределение версии, генерация changelog, понятная история.
## semantic-release и release-please: сравнение
**semantic-release** — npm-пакет, анализирует коммиты, определяет версию, генерирует changelog, создаёт tag и GitHub Release, публикует в npm.
Плюсы: полная автоматизация, гибкая настройка.
Минусы: сложная конфигурация, привязка к npm.
**release-please** — инструмент от Google, создаёт PR с обновлённой версией и changelog. Мерж PR → релиз.
Плюсы: прозрачность, поддержка Node/Python/Go/Rust/Java, простая интеграция.
Минусы: требует ручного мерджа PR.
Я использую semantic-release для npm-библиотек, release-please для остального.
## Автогенерация CHANGELOG.md из коммитов
Оба инструмента генерируют CHANGELOG.md автоматически.
Пример:
```markdown
# Changelog
## [2.1.0](https://github.com/user/repo/compare/v2.0.0...v2.1.0) (2026-05-25)
### Features
* add OAuth2 support ([a1b2c3d](https://github.com/user/repo/commit/a1b2c3d))
### Bug Fixes
* handle null response in getUser ([i7j8k9l](https://github.com/user/repo/commit/i7j8k9l))
```
Группировка по типам, ссылки на коммиты — всё автоматически.
## Интеграция с GitHub Releases
semantic-release создаёт GitHub Release при пуше в main:
```yaml
# .github/workflows/release.yml
name: Release
on:
push:
branches: [main]
jobs:
release:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- uses: actions/setup-node@v3
- run: npm ci
- run: npx semantic-release
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
```
release-please создаёт PR, мерж триггерит релиз:
```yaml
# .github/workflows/release-please.yml
name: Release Please
on:
push:
branches: [main]
jobs:
release-please:
runs-on: ubuntu-latest
steps:
- uses: google-github-actions/release-please-action@v3
with:
release-type: node
package-name: my-package
```
## Примеры настройки для npm/Python/Go
**npm (semantic-release):**
```json
// package.json
{
"version": "0.0.0-development",
"devDependencies": {
"semantic-release": "^21.0.0"
}
}
```
```js
// .releaserc.js
module.exports = {
branches: ['main'],
plugins: [
'@semantic-release/commit-analyzer',
'@semantic-release/release-notes-generator',
'@semantic-release/changelog',
'@semantic-release/npm',
'@semantic-release/github',
],
};
```
**Python (release-please):**
```yaml
- uses: google-github-actions/release-please-action@v3
with:
release-type: python
package-name: my-package
```
**Go (release-please):**
```yaml
- uses: google-github-actions/release-please-action@v3
with:
release-type: go
```
release-please обновит версию в go.mod автоматически.
## Вывод
Автоматическое версионирование экономит время и снижает ошибки. Conventional commits — основа, без них автоматизация не работает.
semantic-release подходит для npm с полной автоматизацией. release-please — для мультиязычных проектов с контролем через PR.
Настройка занимает 15 минут, окупается с первого релиза. Главное — приучить команду писать коммиты по стандарту. Используйте commitlint для проверки формата в pre-commit хуке.
Начните с release-please — он проще и нагляднее.