# 🚀 Скрипты для публикации пакета cupychecker

Этот документ описывает созданные скрипты для быстрой публикации пакета cupychecker в PyPI.

## 📁 Созданные файлы

### Основные скрипты
- `publish.py` - Python скрипт для публикации (основной)
- `publish.sh` - Bash скрипт с удобными командами
- `setup_publishing.sh` - Скрипт первоначальной настройки

### Конфигурация
- `Makefile` - Make команды для публикации
- `.pypirc.example` - Пример конфигурации twine
- `PUBLISH.md` - Подробная документация

## 🚀 Быстрый старт

### 1. Первоначальная настройка

```bash
# Запустите скрипт настройки
./setup_publishing.sh

# Или вручную:
pip3 install --upgrade setuptools wheel build twine
pip3 install -e .
pip3 install -r ../tests/requirements-test.txt
cp .pypirc.example .pypirc
# Отредактируйте .pypirc и вставьте ваши API токены
```

### 2. Настройка API токенов

```bash
# Скопируйте пример конфигурации
cp .pypirc.example .pypirc

# Отредактируйте .pypirc
nano .pypirc
```

Вставьте ваши токены:
```ini
[pypi]
username = __token__
password = pypi-your_token_here

[testpypi]
repository = https://test.pypi.org/legacy/
username = __token__
password = testpypi-your_token_here
```

### 3. Публикация

```bash
# Публикация patch версии (0.1.0 -> 0.1.1)
./publish.sh publish

# Публикация minor версии (0.1.0 -> 0.2.0)
./publish.sh publish-minor

# Публикация на TestPyPI
./publish.sh publish-test
```

## 🛠 Способы использования

### 1. Python скрипт (publish.py)

```bash
# Показать справку
python3 publish.py --help

# Публикация patch версии
python3 publish.py

# Публикация minor версии
python3 publish.py --version-type minor

# Публикация major версии
python3 publish.py --version-type major

# Публикация конкретной версии
python3 publish.py --version 1.2.3

# Публикация на TestPyPI
python3 publish.py --test-only

# Только сборка (без публикации)
python3 publish.py --build-only

# Пропустить тесты
python3 publish.py --skip-tests
```

### 2. Bash скрипт (publish.sh)

```bash
# Показать справку
./publish.sh help

# Основные команды
./publish.sh publish          # Patch версия
./publish.sh publish-minor    # Minor версия
./publish.sh publish-major    # Major версия
./publish.sh publish-test     # TestPyPI
./publish.sh publish-version 1.2.3  # Конкретная версия

# Алиасы
./publish.sh p                # publish
./publish.sh pt               # publish-test
./publish.sh pp               # publish-patch
./publish.sh pm               # publish-minor
./publish.sh pmj              # publish-major
./publish.sh pv 1.2.3         # publish-version

# Утилиты
./publish.sh test             # Запустить тесты
./publish.sh build            # Собрать пакет
./publish.sh clean            # Очистить сборки
./publish.sh dev              # Быстрая разработка
```

### 3. Makefile

```bash
# Показать справку
make help

# Основные команды
make publish                  # Patch версия
make publish-minor            # Minor версия
make publish-major            # Major версия
make publish-test             # TestPyPI
make publish-version VERSION=1.2.3  # Конкретная версия

# Алиасы
make p                        # publish
make pt                       # publish-test
make pp                       # publish-patch
make pm                       # publish-minor
make pmj                      # publish-major
make pv VERSION=1.2.3         # publish-version

# Утилиты
make test                     # Запустить тесты
make build                    # Собрать пакет
make clean                    # Очистить сборки
make dev-setup                # Настроить окружение
```

## 📦 Процесс публикации

Скрипт `publish.py` выполняет следующие шаги:

1. **Обновление версии** - автоматически увеличивает версию в `setup.cfg`
2. **Запуск тестов** - проверяет, что все тесты проходят
3. **Очистка** - удаляет предыдущие сборки
4. **Сборка пакета** - создает wheel и source distribution
5. **Проверка пакета** - проверяет пакет с помощью twine
6. **Создание git тега** - создает тег для новой версии
7. **Публикация** - загружает пакет в PyPI или TestPyPI

## 🧪 Рекомендуемый workflow

### 1. Разработка

```bash
# Настройка окружения
./setup_publishing.sh

# Быстрая разработка
./publish.sh dev

# Тестирование
./publish.sh test
```

### 2. Тестирование публикации

```bash
# Сначала TestPyPI
./publish.sh publish-test

# Установите с TestPyPI
pip3 install --index-url https://test.pypi.org/simple/ cupychecker

# Протестируйте
python3 -c "import cupychecker; print('OK')"
```

### 3. Публикация на PyPI

```bash
# Публикация на PyPI
./publish.sh publish

# Или конкретная версия
./publish.sh publish-version 1.2.3
```

## 🔧 Настройка окружения

### Автоматическая настройка

```bash
# Полная настройка
./setup_publishing.sh
```

### Ручная настройка

```bash
# 1. Установите зависимости
pip3 install --upgrade setuptools wheel build twine

# 2. Установите пакет в режиме разработки
pip3 install -e .

# 3. Установите зависимости для тестов
pip3 install -r ../tests/requirements-test.txt

# 4. Настройте .pypirc
cp .pypirc.example .pypirc
# Отредактируйте .pypirc и вставьте ваши токены
```

## 📝 Управление версиями

### Семантическое версионирование

- **MAJOR** (1.0.0) - несовместимые изменения API
- **MINOR** (0.1.0) - новая функциональность с обратной совместимостью
- **PATCH** (0.0.1) - исправления ошибок с обратной совместимостью

### Примеры

```bash
# Текущая версия: 0.1.0

# Patch версия (исправления)
./publish.sh publish-patch
# Результат: 0.1.1

# Minor версия (новая функциональность)
./publish.sh publish-minor
# Результат: 0.2.0

# Major версия (breaking changes)
./publish.sh publish-major
# Результат: 1.0.0
```

## 🔍 Проверка пакета

### Локальная проверка

```bash
# Собрать пакет
./publish.sh build

# Проверить пакет
python3 -m twine check dist/*

# Установить локально
pip3 install dist/cupychecker-*.whl
```

### Проверка на TestPyPI

```bash
# Публиковать на TestPyPI
./publish.sh publish-test

# Установить с TestPyPI
pip3 install --index-url https://test.pypi.org/simple/ cupychecker

# Проверить работу
python3 -c "from cupychecker.helpers import TestHelper; print('OK')"
```

## 🚨 Решение проблем

### Ошибка "Invalid credentials"

```bash
# Проверьте .pypirc
cat .pypirc

# Убедитесь, что токены правильные
python3 -m twine check dist/*
```

### Ошибка "Package already exists"

```bash
# Увеличьте версию
./publish.sh publish-patch

# Или укажите конкретную версию
./publish.sh publish-version 1.2.3
```

### Ошибка "Tests failed"

```bash
# Запустите тесты отдельно
cd ../tests && python3 run_tests.py

# Исправьте ошибки и повторите
./publish.sh publish
```

## 📚 Полезные команды

### Информация о пакете

```bash
# Показать текущую версию
./publish.sh version

# Показать файлы в dist
./publish.sh files

# Проверить пакет
python3 -m twine check dist/*
```

### Отладка

```bash
# Подробный вывод
python3 publish.py --version-type patch -v

# Только сборка
python3 publish.py --build-only

# Пропустить тесты
python3 publish.py --skip-tests
```

## 🔗 Полезные ссылки

- [PyPI](https://pypi.org/project/cupychecker/)
- [TestPyPI](https://test.pypi.org/project/cupychecker/)
- [Twine документация](https://twine.readthedocs.io/)
- [Python Packaging User Guide](https://packaging.python.org/)

## 📞 Поддержка

Если у вас возникли проблемы:

1. Проверьте этот документ
2. Запустите тесты: `./publish.sh test`
3. Проверьте настройки: `python3 -m twine check dist/*`
4. Создайте issue в репозитории

## 🎉 Готово!

Теперь у вас есть полный набор инструментов для публикации пакета cupychecker:

- ✅ Автоматическое управление версиями
- ✅ Запуск тестов перед публикацией
- ✅ Сборка и проверка пакета
- ✅ Публикация на PyPI и TestPyPI
- ✅ Создание git тегов
- ✅ Множественные интерфейсы (Python, Bash, Make)
- ✅ Подробная документация

Начните с `./setup_publishing.sh` и следуйте инструкциям! 🚀
