Как поддерживаешь версионность?

Как поддерживаешь версионность

Версионность — система управления версиями кода, зависимостей и релизов приложения. Версионность отслеживает изменения, позволяет откатываться к старым версиям, контролировать обновления и понимать совместимость между версиями.

Семантическое версирование (Semantic Versioning)

Стандартный формат MAJOR.MINOR.PATCH с понятным смыслом каждого числа:

2.3.1
│ │ │
│ │ └─ PATCH - исправления ошибок (2.3.0 -> 2.3.1, обратно совместимо)
│ └─── MINOR - новые возможности (2.2.0 -> 2.3.0, обратно совместимо)
└───── MAJOR - несовместимые изменения (1.0.0 -> 2.0.0, обновление обязательно)

Примеры:

"1.0.0"   // Первый релиз
"1.0.1"   // Исправлена критичная ошибка
"1.1.0"   // Добавлена новая фича (не ломает старый код)
"2.0.0"   // Крупные несовместимые изменения
"3.5.2-beta.1" // Бета-версия

Git Tags для версионности

# Создать тег версии и отправить на сервер
git tag v1.0.0
git push origin v1.0.0

# Создать аннотированный тег с описанием
git tag -a v1.0.0 -m "Release version 1.0.0"

# Список всех тегов
git tag --list

# Получить информацию о теге
git show v1.0.0

# Удалить локальный тег
git tag --delete v1.0.0

# Удалить тег на удалённом репо
git push origin --delete v1.0.0

package.json версионность

{
  "name": "prepbro-frontend",
  "version": "1.2.5",
  "dependencies": {
    "react": "^19.0.0",
    "next": "~16.0.0",
    "tailwindcss": "4.0.0"
  }
}

Символы версионирования зависимостей:

"^19.0.0"   // Caret: обновления до 19.x.x (MINOR и PATCH)
"~16.0.0"   // Tilde: обновления до 16.0.x (только PATCH)
"4.0.0"     // Точная версия, без автообновлений
">=1.0.0 <2.0.0" // Диапазон версий
"*"         // Любая версия (опасно, не используй)

Changelog - документирование изменений

# Changelog

## [2.0.0] - 2026-04-02
### Breaking Changes
- API требует authentication для всех endpoints
- Переделан интерфейс компонента Question

### Added
- Поддержка тёмного режима
- Новая страница профиля пользователя
- WebSocket для real-time обновлений

### Fixed
- Исправлена ошибка при скролле на мобильных
- Проблема с кэшированием на Firefox

### Deprecated
- Старый API endpoint `/api/v0/questions` (удалится в 3.0.0)

### Removed
- Удалена поддержка IE11 и Edge Chromium < 80

## [1.5.0] - 2026-03-15
### Added
- Кэширование результатов запросов

Версионность зависимостей в CI/CD

# .github/workflows/release.yml
name: Release
on:
  push:
    tags:
      - "v*"

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Extract version from tag
        run: echo "VERSION=${GITHUB_REF#refs/tags/}" >> $GITHUB_ENV
      
      - name: Build
        run: npm run build
      
      - name: Create release notes
        run: echo "Deployed ${{ env.VERSION }}"
      
      - name: Deploy to production
        run: npm run deploy

Отображение версии на фронте

// lib/version.ts
export const APP_VERSION = process.env.NEXT_PUBLIC_APP_VERSION || "dev";
export const BUILD_DATE = process.env.NEXT_PUBLIC_BUILD_DATE || "unknown";

// components/Footer.tsx
import { APP_VERSION, BUILD_DATE } from "@/lib/version";

export function Footer() {
  return (
    <footer className="text-center text-sm text-content-secondary">
      <p>PrepBro v{APP_VERSION}</p>
      <p>Built: {BUILD_DATE}</p>
    </footer>
  );
}

Next.js конфигурация версионности

// next.config.js
/** @type {import(next).NextConfig} */
const nextConfig = {
  env: {
    NEXT_PUBLIC_APP_VERSION: process.env.npm_package_version || "0.0.0",
    NEXT_PUBLIC_BUILD_DATE: new Date().toISOString(),
    NEXT_PUBLIC_GIT_SHA: process.env.GITHUB_SHA || "local"
  }
};

module.exports = nextConfig;

Управление зависимостями

# Проверить устаревшие зависимости
npm outdated

# Обновить все зависимости (safe)
npm update

# Обновить конкретный пакет на последнюю версию
npm install react@latest

# Зафиксировать версии (package-lock.json гарантирует одинаковую версию)
npm ci

# Проверить уязвимости безопасности
npm audit

# Исправить уязвимости автоматически
npm audit fix

# Проверить только высокие уязвимости
npm audit --audit-level=high

Стратегия обновления

{
  "dependencies": {
    "react": "^19.0.0",
    "next": "~16.0.0",
    "tailwindcss": "4.0.0"
  },
  "devDependencies": {
    "typescript": "^5.0.0",
    "eslint": "^8.50.0"
  }
}

Правило:

• Мажор версии (^) для разработки (проще обновить)
• Минор версия (~) для production-критичных
• Точная версия для очень критичных зависимостей

API версионность

// Разные версии API одновременно
router.get("/api/v1/questions", v1QuestionHandler);
router.get("/api/v2/questions", v2QuestionHandler);

// v1 возвращает другой формат
// v1: { id, text, options }
// v2: { id, title, description, variants, difficulty }

// Со временем v1 помечается как deprecated
res.headers["Deprecation"] = "true";
res.headers["Sunset"] = new Date(Date.now() + 30*24*60*60*1000).toUTCString();

Feature Flags для плавного переката

// lib/features.ts
export const FEATURES = {
  NEW_UI_COMPONENTS: process.env.NEXT_PUBLIC_FEATURE_NEW_UI === "true",
  DARK_MODE: process.env.NEXT_PUBLIC_FEATURE_DARK_MODE === "true",
  BETA_API_V2: process.env.NEXT_PUBLIC_FEATURE_API_V2 === "true"
};

// components/Header.tsx
import { FEATURES } from "@/lib/features";

export function Header() {
  if (FEATURES.NEW_UI_COMPONENTS) {
    return <HeaderNewVersion />;
  }
  return <HeaderOldVersion />;
}

Чек-лист версионности

1. Используй Semantic Versioning (MAJOR.MINOR.PATCH)
2. Git tag для каждого релиза (v1.0.0)
3. Ведение Changelog с описанием изменений
4. package.json версия совпадает с тегами
5. package-lock.json заафиксирован в репо
6. CI/CD автоматизирует релизы по тегам
7. Поддержка старых версий API некоторое время (deprecated)
8. Feature flags для плавного переката новых функций

Итог: Хорошая версионность критична для масштабируемого приложения. Она позволяет контролировать обновления, отслеживать совместимость, быстро откатываться при проблемах и планировать миграцию пользователей на новые версии.