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