104 lines
5.8 KiB
Markdown
104 lines
5.8 KiB
Markdown
# Правила оформления Changelog для документации
|
||
|
||
## Общие требования
|
||
|
||
- **Формат**: Markdown
|
||
- **Структура**: Одна версия = одна страница
|
||
- **Стиль**: Профессиональный, лаконичный, без маркетинговых лозунгов
|
||
- **Язык**: Русский
|
||
- **Целевая аудитория**: Разработчики и владельцы магазинов
|
||
- **Содержимое**: Только ключевые изменения, без лишних технических деталей
|
||
|
||
## Структура страницы
|
||
|
||
### Вводный абзац
|
||
- Краткое описание релиза (1-2 предложения)
|
||
- Дополнить 1-2 предложениями о ключевых изменениях
|
||
- Упоминать основные фичи и улучшения
|
||
|
||
### Разделы (строго в этом порядке)
|
||
|
||
1. **🚀 Добавлено** - новые функции и возможности
|
||
2. **✨ Улучшено** - улучшения существующих функций
|
||
3. **🐞 Исправлено** - исправленные ошибки
|
||
4. **⚠️ Несовместимые изменения** - изменения без обратной совместимости
|
||
5. **🔧 Технические изменения** - технические изменения (отдельный раздел)
|
||
|
||
### Правила для разделов
|
||
|
||
- Раздел **НЕ** добавлять, если в нём нет пунктов
|
||
- Использовать маркдаун-списки, без нумерации
|
||
- Не добавлять ссылок, если они явно не указаны
|
||
- Не добавлять лишних пояснений, выводов и заключений
|
||
- Выводить только содержимое Markdown-файла, без комментариев
|
||
|
||
## Разделение изменений
|
||
|
||
### Бизнес-логика и процессы
|
||
Разделы "Добавлено", "Улучшено", "Исправлено", "Несовместимые изменения" содержат только изменения, связанные с:
|
||
- Бизнес-процессами магазина
|
||
- Пользовательским опытом
|
||
- Функциональностью для владельцев магазинов
|
||
- Продающими фичами
|
||
|
||
### Технические изменения
|
||
Все технические изменения выносятся в отдельный раздел **🔧 Технические изменения**:
|
||
- Без подразделов, всё в одном списке
|
||
- Только самые ключевые технические изменения
|
||
- Не расписывать детали, которые не интересны пользователю
|
||
|
||
## Стиль написания
|
||
|
||
### Терминология
|
||
- Английские термины писать по-английски (например: "navbar", а не "навбар")
|
||
- Избегать технических терминов в бизнес-разделах (например: "customer_id" → "автоматическое связывание покупателей")
|
||
|
||
### Описания
|
||
|
||
**Для ключевых продающих фич:**
|
||
- Давать подробное описание с деталями
|
||
- Указывать возможности и преимущества
|
||
- Подчеркивать ценность для пользователя
|
||
|
||
**Для технических изменений:**
|
||
- Кратко, только ключевое
|
||
- Без лишних деталей
|
||
|
||
**Для обычных функций:**
|
||
- Лаконично, но информативно
|
||
- Фокус на пользе для пользователя
|
||
|
||
## Порядок размещения
|
||
|
||
### В разделе "Добавлено"
|
||
Ключевые продающие фичи размещать **первыми**:
|
||
1. Система конфигурации главной страницы через блоки
|
||
2. Конструктор форм на базе FormKit
|
||
3. Интеграция с Яндекс.Метрикой
|
||
4. Политика конфиденциальности
|
||
5. Поддержка купонов и подарочных сертификатов
|
||
6. Остальные функции
|
||
|
||
## Примеры правильных формулировок
|
||
|
||
### ✅ Хорошо
|
||
- "Автоматическое связывание покупателей Telegram с покупателями OpenCart: система автоматически находит и связывает покупателей из Telegram-магазина с существующими покупателями в OpenCart по email или номеру телефона, создавая единую базу клиентов"
|
||
|
||
### ❌ Плохо
|
||
- "Сохранение customer_id вместе с заказом для связи с клиентами OpenCart: автоматическая связь заказов из Telegram с покупателями в OpenCart, единая база клиентов"
|
||
|
||
### ✅ Хорошо
|
||
- "Navbar с логотипом и названием приложения"
|
||
|
||
### ❌ Плохо
|
||
- "Навбар с логотипом и названием приложения"
|
||
|
||
## Что не включать
|
||
|
||
- Внутренние детали разработки (тесты, статический анализ, обфускация)
|
||
- Технические детали, не интересные пользователям
|
||
- Избыточные технические описания
|
||
- Маркетинговые лозунги и призывы
|
||
|
||
|