gitverse-release 2.0.1 → 3.0.0

package/README.md

@@ -1,51 +1,54 @@
-# @gitverse/release
+# GitVerse Release
 
-> Automated release tool for GitVerse repositories with Conventional Commits support
-
-[![npm version](https://img.shields.io/npm/v/@gitverse/release.svg)](https://www.npmjs.com/package/@gitverse/release)
+[![npm version](https://img.shields.io/npm/v/gitverse-release.svg)](https://www.npmjs.com/package/gitverse-release)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![Test Coverage](https://img.shields.io/badge/coverage-99.85%25-brightgreen.svg)](https://gitverse.ru/RainyPixel/gitverse-sdk)
+
+Инструмент автоматизации релизов для GitVerse репозиториев с поддержкой Conventional Commits и семантического версионирования.
 
-## Features
+## Возможности
 
-- ✅ **Automatic versioning** based on Conventional Commits
-- 📝 **CHANGELOG generation** grouped by commit types
-- 🌐 **GitVerse API integration** for creating releases
-- 📦 **Monorepo support** with independent versioning
-- 🏷️ **Automatic git tags and commits**
-- 🔍 **Dry-run mode** for safe testing
-- ⚙️ **Flexible configuration** via `.gitversereleaserc.json`
+- ✅ **Автоматическое версионирование** на основе Conventional Commits
+- 📝 **Генерация CHANGELOG** с группировкой по типам коммитов
+- 🌐 **Интеграция с GitVerse API** для создания релизов
+- 📦 **Поддержка монорепозиториев** с независимым версионированием
+- 🏷️ **Автоматические git теги и коммиты**
+- 🔍 **Режим dry-run** для безопасного тестирования
+- ⚙️ **Гибкая конфигурация** через `.gitversereleaserc.json`
 
-## Installation
+## Установка
 
 ```bash
-# Using npm
-npm install -D @gitverse/release
+# npm
+npm install -D gitverse-release
 
-# Using bun
-bun add -d @gitverse/release
+# bun
+bun add -d gitverse-release
 
-# Using yarn
-yarn add -D @gitverse/release
+# yarn
+yarn add -D gitverse-release
 
-# Using pnpm
-pnpm add -D @gitverse/release
+# pnpm
+pnpm add -D gitverse-release
 ```
 
-## Quick Start
+## Быстрый старт
 
-### 1. Basic Usage
+> ⚠️ **Важно:** Для создания релизов в GitVerse необходимо настроить `GITVERSE_TOKEN`. Без токена инструмент работает в урезанном режиме (только локальные теги и CHANGELOG). См. [Настройка GITVERSE_TOKEN](#️-настройка-gitverse_token)
+
+### 1. Базовое использование
 
 ```bash
-# Create release (dry-run for testing)
-npx @gitverse/release --dry-run
+# Создать релиз (dry-run для тестирования)
+npx gitverse-release --dry-run
 
-# Create and publish release
-npx @gitverse/release
+# Создать и опубликовать релиз
+npx gitverse-release
 ```
 
-### 2. Configuration
+### 2. Конфигурация
 
-Create `.gitversereleaserc.json` in project root:
+Создайте `.gitversereleaserc.json` в корне проекта:
 
 ```json
 {
@@ -57,10 +60,10 @@ Create `.gitversereleaserc.json` in project root:
   },
   "changelog": {
     "types": {
-      "feat": "✨ Features",
-      "fix": "🐛 Bug Fixes",
-      "perf": "⚡ Performance",
-      "docs": "📝 Documentation"
+      "feat": "✨ Новые возможности",
+      "fix": "🐛 Исправления",
+      "perf": "⚡ Производительность",
+      "docs": "📝 Документация"
     },
     "showHash": true,
     "showAuthor": true
@@ -71,66 +74,72 @@ Create `.gitversereleaserc.json` in project root:
 }
 ```
 
-### 3. Add to package.json
+### 3. Добавьте в package.json
 
 ```json
 {
   "scripts": {
-    "release": "@gitverse/release",
-    "release:dry": "@gitverse/release --dry-run"
+    "release": "gitverse-release",
+    "release:dry": "gitverse-release --dry-run"
   }
 }
 ```
 
-## Usage
+## Использование
 
 ### Conventional Commits
 
-The package automatically determines version bump based on commits:
+Инструмент автоматически определяет тип версии на основе коммитов:
 
 ```bash
 # Patch (1.0.0 → 1.0.1)
-git commit -m "fix: resolve validation error"
+git commit -m "fix: исправлена ошибка валидации"
 
 # Minor (1.0.0 → 1.1.0)
-git commit -m "feat: add new API endpoint"
+git commit -m "feat: добавлен новый API эндпоинт"
 
 # Major (1.0.0 → 2.0.0)
-git commit -m "feat!: change API response format"
-# or
-git commit -m "feat: new feature
+git commit -m "feat!: изменен формат ответа API"
+# или
+git commit -m "feat: новая функция
 
-BREAKING CHANGE: changed configuration format"
+BREAKING CHANGE: изменен формат конфигурации"
 ```
 
-### Programmatic Usage
+### Программное использование
 
 ```typescript
-import { release } from "@gitverse/release";
+import { release } from "gitverse-release";
 
-// Simple release
+// Простой релиз
 const result = await release();
 
 console.log(result.success); // true
 console.log(result.newVersion); // "1.1.0"
 console.log(result.tag); // "v1.1.0"
 
-// With options
+// С опциями
 const result = await release(undefined, {
   dryRun: true,
   version: "2.0.0",
   skipGitStatusCheck: false,
 });
 
-// For monorepo
+// Для монорепозитория
 const result = await release("my-package", {
   dryRun: false,
 });
 ```
 
-## Monorepo Support
+> **Примечание для GitVerse Actions:**
+> В GitVerse Actions автоматически доступны переменные окружения:
+> - `GITVERSE_TOKEN` - должен быть настроен в Secrets (см. [Настройка](#️-настройка-gitverse_token))
+> - `GITVERSE_PUBLIC_API_URL` - автоматически доступен (`https://api.gitverse.ru/`)
+> - `GITHUB_REPOSITORY` - имя репозитория в формате `owner/repo`
+
+## Поддержка монорепозиториев
 
-### Configuration
+### Конфигурация
 
 ```json
 {
@@ -156,32 +165,32 @@ const result = await release("my-package", {
 }
 ```
 
-### Usage
+### Использование
 
 ```bash
-# Release specific package
-npx @gitverse/release core
+# Релиз конкретного пакета
+npx gitverse-release core
 
-# Dry-run for package
-npx @gitverse/release ui --dry-run
+# Dry-run для пакета
+npx gitverse-release ui --dry-run
 ```
 
-### Commit Filtering by Scope
+### Фильтрация коммитов по scope
 
 ```bash
-# Commits for "core" package
-git commit -m "feat(core): add new function"
+# Коммиты для пакета "core"
+git commit -m "feat(core): добавлена новая функция"
 
-# Commits for "ui" package
-git commit -m "fix(ui): resolve component bug"
+# Коммиты для пакета "ui"
+git commit -m "fix(ui): исправлена ошибка компонента"
 
-# Common commits (affect all packages)
-git commit -m "chore: update dependencies"
+# Общие коммиты (влияют на все пакеты)
+git commit -m "chore: обновлены зависимости"
 ```
 
-## Configuration
+## Конфигурация
 
-### Full Example
+### Полный пример
 
 ```json
 {
@@ -193,16 +202,16 @@ git commit -m "chore: update dependencies"
   },
   "changelog": {
     "types": {
-      "feat": "✨ Features",
-      "fix": "🐛 Bug Fixes",
-      "perf": "⚡ Performance Improvements",
-      "refactor": "♻️ Code Refactoring",
-      "docs": "📝 Documentation",
-      "style": "💄 Styles",
-      "test": "✅ Tests",
-      "build": "🔧 Build System",
+      "feat": "✨ Новые возможности",
+      "fix": "🐛 Исправления",
+      "perf": "⚡ Улучшения производительности",
+      "refactor": "♻️ Рефакторинг",
+      "docs": "📝 Документация",
+      "style": "💄 Стили",
+      "test": "✅ Тесты",
+      "build": "🔧 Сборка",
       "ci": "👷 CI/CD",
-      "chore": "🧹 Chores"
+      "chore": "🧹 Прочее"
     },
     "showHash": true,
     "showAuthor": true
@@ -223,35 +232,88 @@ git commit -m "chore: update dependencies"
 }
 ```
 
-### Environment Variables
+### Переменные окружения
 
 ```bash
-# GitVerse token for creating releases
+# Токен GitVerse для создания релизов
 export GITVERSE_TOKEN="your-token-here"
 
-# Or via .env file
+# Или через .env файл
 echo "GITVERSE_TOKEN=your-token" >> .env
 ```
 
-## CLI Options
+### ⚠️ Настройка GITVERSE_TOKEN
+
+**КРИТИЧЕСКИ ВАЖНО:** Без настройки `GITVERSE_TOKEN` инструмент работает в **урезанном режиме**:
+
+✅ **С токеном (полный режим):**
+- Автоматическое создание релизов в GitVerse
+- Публикация changelog в релиз
+- Загрузка ассетов релиза
+- Push тегов и коммитов в удаленный репозиторий
+
+⚠️ **Без токена (урезанный режим):**
+- ❌ НЕТ создания релизов в GitVerse
+- ✅ Генерация CHANGELOG локально
+- ✅ Создание git тегов локально
+- ✅ Коммиты изменений локально
+
+#### Настройка токена для GitVerse Actions
+
+**Важно:** `GITVERSE_TOKEN` **НЕ предоставляется автоматически** в GitVerse Actions!
+
+**Шаг 1: Создайте Personal Access Token**
+1. Перейдите в GitVerse: **Settings** → **Applications** → **Generate New Token**
+2. Выберите необходимые права:
+   - `repo` - полный доступ к репозиториям (обязательно для релизов)
+3. Скопируйте токен (показывается только один раз!)
+
+**Шаг 2: Добавьте токен в Secrets репозитория**
+1. В репозитории: **Settings** → **Secrets and Variables** → **Actions**
+2. Нажмите **New repository secret**
+3. **Name:** `GITVERSE_TOKEN`
+4. **Value:** ваш Personal Access Token
+5. Сохраните
+
+**Шаг 3: Используйте в workflow**
+```yaml
+env:
+  GITVERSE_TOKEN: ${{ secrets.GITVERSE_TOKEN }}
+```
+
+**Шаг 4: Проверка (рекомендуется)**
+```yaml
+- name: Validate GITVERSE_TOKEN
+  run: |
+    if [ -z "$GITVERSE_TOKEN" ]; then
+      echo "❌ ERROR: GITVERSE_TOKEN is not set!"
+      echo "Please add GITVERSE_TOKEN to repository secrets."
+      exit 1
+    fi
+    echo "✅ GITVERSE_TOKEN is configured"
+```
+
+## CLI опции
 
 ```
-npx @gitverse/release [package] [options]
+npx gitverse-release [package] [options]
 
-Arguments:
-  package              Package name for release (for monorepos)
+Аргументы:
+  package              Имя пакета для релиза (для монорепозиториев)
 
-Options:
-  --dry-run            Run without making changes
-  --version <version>  Specify exact version
-  --skip-git-check     Skip git status check
-  --help               Show help
+Опции:
+  --dry-run            Запуск без внесения изменений
+  --version <version>  Указать конкретную версию
+  --skip-git-check     Пропустить проверку git статуса
+  --help               Показать справку
 ```
 
-## CI/CD Integration
+## CI/CD интеграция
 
 ### GitVerse Actions
 
+⚠️ **Перед использованием:** Убедитесь, что `GITVERSE_TOKEN` добавлен в Secrets репозитория (см. [Настройка GITVERSE_TOKEN](#️-настройка-gitverse_token))
+
 ```yaml
 name: Release
 
@@ -259,6 +321,7 @@ on:
   workflow_dispatch:
 
 env:
+  # ОБЯЗАТЕЛЬНО: Добавьте GITVERSE_TOKEN в Secrets репозитория!
   GITVERSE_TOKEN: ${{ secrets.GITVERSE_TOKEN }}
 
 jobs:
@@ -273,6 +336,17 @@ jobs:
 
       - run: bun install
 
+      # ВАЖНО: Проверка наличия токена перед релизом
+      - name: Validate GITVERSE_TOKEN
+        run: |
+          if [ -z "$GITVERSE_TOKEN" ]; then
+            echo "❌ ERROR: GITVERSE_TOKEN is not set!"
+            echo "Please add GITVERSE_TOKEN to repository secrets."
+            echo "See: Settings → Secrets and Variables → Actions"
+            exit 1
+          fi
+          echo "✅ GITVERSE_TOKEN is configured"
+
       - name: Configure Git
         run: |
           git config user.name "GitVerse CI"
@@ -282,20 +356,49 @@ jobs:
         run: bun run release
 ```
 
-## License
+**Что происходит в этом workflow:**
+1. ✅ Проверяет наличие `GITVERSE_TOKEN` (workflow упадет с ошибкой, если токен не настроен)
+2. ✅ Устанавливает зависимости
+3. ✅ Настраивает git для создания коммитов
+4. ✅ Создает релиз с полным функционалом (CHANGELOG, теги, GitVerse release)
+5. ✅ Автоматически публикует в GitVerse
+
+## Разработка
+
+```bash
+# Установка зависимостей
+bun install
+
+# Запуск тестов
+bun test
+
+# Проверка покрытия
+bun test:coverage
+
+# Сборка проекта
+bun run build
+
+# Линтинг
+bun run lint
+bun run lint:fix
+```
+
+## Лицензия
 
-MIT © RainyPixel
+MIT © [RainyPixel](https://gitverse.ru/RainyPixel)
 
-## Links
+## Полезные ссылки
 
-- [GitVerse SDK](https://gitverse.ru/RainyPixel/gitverse-sdk)
-- [Conventional Commits](https://www.conventionalcommits.org/)
-- [Keep a Changelog](https://keepachangelog.com/)
+- [GitVerse SDK](https://gitverse.ru/RainyPixel/gitverse-sdk) - Основной репозиторий
+- [Conventional Commits](https://www.conventionalcommits.org/ru/) - Спецификация
+- [Keep a Changelog](https://keepachangelog.com/ru/) - Руководство по CHANGELOG
+- [Semantic Versioning](https://semver.org/lang/ru/) - Семантическое версионирование
+- [npm пакет](https://www.npmjs.com/package/gitverse-release)
 
-## Found a bug?
+## Сообщить об ошибке
 
-Create an issue on [GitVerse](https://gitverse.ru/RainyPixel/gitverse-sdk/issues)
+Создайте issue на [GitVerse](https://gitverse.ru/RainyPixel/gitverse-sdk/issues)
 
 ---
 
-Made with ❤️ for GitVerse
+Сделано с ❤️ для GitVerse