0 Сохранить Поделиться
Подписаться на автора
Пожаловаться
Docker multi-stage builds: оптимизация размера образа # Semantic versioning и автоматический changelog
Версионирование — это не просто цифры в package.json. Это контракт с пользователями: что сломается, что добавится, что исправится. Когда проект растёт, ручное ведение версий и changelog превращается в рутину, где легко ошибиться.
Я перевёл несколько проектов на автоматическое версионирование и генерацию 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) — исправления багов, обратно совместимые.
Примеры:
- Удалили метод из публичного API → major.
- Добавили новый опциональный параметр → minor.
- Исправили баг в существующей логике → patch.
До версии 1.0.0 проект считается нестабильным, breaking changes допустимы в minor.
## Conventional commits: формат и зачем нужен
Conventional commits — стандарт формата коммитов, который позволяет автоматически определять тип изменения.
Формат:
```
():
```
Типы:
- `feat:` — новая функциональность (→ minor bump).
- `fix:` — исправление бага (→ patch bump).
- `BREAKING CHANGE:` в footer или `!` после типа (→ major bump).
- `docs:`, `style:`, `refactor:`, `test:`, `chore:` — не влияют на версию.
Примеры:
```
feat(auth): add OAuth2 support
fix(api): handle null response in getUser
feat!: remove deprecated login method
BREAKING CHANGE: login() now requires email instead of username
```
Зачем нужен:
- Автоматическое определение версии из истории коммитов.
- Генерация changelog с группировкой по типам.
- Понятная история изменений без чтения кода.
## semantic-release и release-please: сравнение
**semantic-release** — npm-пакет, который анализирует коммиты, определяет версию, генерирует changelog, создаёт git tag и GitHub Release, публикует в npm.
Плюсы:
- Полная автоматизация: от коммита до публикации.
- Гибкая настройка через плагины.
- Поддержка npm, Docker, GitHub Releases.
Минусы:
- Сложная конфигурация для нестандартных сценариев.
- Привязка к npm экосистеме (хотя есть плагины для других).
**release-please** — инструмент от Google, создаёт PR с обновлённой версией и changelog. Мерж PR → создание релиза.
Плюсы:
- Прозрачность: видишь изменения до релиза.
- Поддержка множества языков: Node, Python, Go, Rust, Java.
- Простая интеграция с GitHub Actions.
Минусы:
- Требует ручного мерджа PR.
- Меньше гибкости в настройке.
Я использую semantic-release для npm-библиотек, release-please для всего остального.
## Автогенерация CHANGELOG.md из коммитов
Оба инструмента генерируют CHANGELOG.md автоматически.
Пример сгенерированного changelog:
```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))
* support custom themes ([e4f5g6h](https://github.com/user/repo/commit/e4f5g6h))
### 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
with:
node-version: 18
- 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
{
"name": "my-package",
"version": "0.0.0-development",
"scripts": {
"semantic-release": "semantic-release"
},
"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',
'@semantic-release/git',
],
};
```
**Python (release-please):**
```yaml
# .github/workflows/release-please.yml
- uses: google-github-actions/release-please-action@v3
with:
release-type: python
package-name: my-package
```
```toml
# pyproject.toml
[tool.release-please]
release-type = "python"
```
**Go (release-please):**
```yaml
- uses: google-github-actions/release-please-action@v3
with:
release-type: go
package-name: my-package
```
release-please обновит версию в go.mod автоматически.
## Вывод
Автоматическое версионирование экономит время и снижает ошибки. Conventional commits — основа, без них автоматизация не работает.
semantic-release подходит для npm-библиотек с полной автоматизацией. release-please — для мультиязычных проектов, где нужен контроль через PR.
Настройка занимает 15 минут, окупается с первого релиза. Главное — приучить команду писать коммиты по стандарту. Используйте commitlint для проверки формата коммитов в pre-commit хуке.
Начните с release-please, если не уверены — он проще и нагляднее. Переход на semantic-release всегда можно сделать позже.