Рекомендации по отчётам об ошибках

Эффективные отчёты об ошибках и предложения функций критически важны для развития XOOPS. Это руководство помогает вам создавать качественные ошибки.

---

Перед отправкой отчёта

Проверьте существующие ошибки

Всегда сначала ищите:

1. Перейдите в GitHub Issues
2. Поищите ключевые слова, связанные с вашей проблемой
3. Проверьте закрытые ошибки - могут быть уже решены
4. Посмотрите pull requests - могут быть в разработке

Используйте фильтры поиска:

• is:issue is:open label:bug - Открытые ошибки
• is:issue is:open label:feature - Открытые предложения функций
• is:issue sort:updated - Недавно обновленные ошибки

Это действительно проблема?

Сначала подумайте:

• Проблема конфигурации? - Проверьте документацию
• Вопрос по использованию? - Спросите на форумах или в сообществе Discord
• Проблема безопасности? - См. раздел #security-issues ниже
• Специфично для модуля? - Сообщите разработчику модуля
• Специфично для темы? - Сообщите автору темы

---

Типы ошибок

Отчёт об ошибке

Ошибка - это неожиданное поведение или дефект.

Примеры:

• Вход не работает
• Ошибки базы данных
• Отсутствующая валидация формы
• Уязвимость безопасности

Предложение функции

Предложение функции - это предложение новой функциональности.

Примеры:

• Добавить поддержку новой функции
• Улучшить существующую функциональность
• Добавить отсутствующую документацию
• Улучшения производительности

Улучшение

Улучшение улучшает существующую функциональность.

Примеры:

• Лучшие сообщения об ошибках
• Улучшенная производительность
• Улучшенный дизайн API
• Улучшенный пользовательский опыт

Документация

Проблемы документации включают отсутствующую или неправильную документацию.

Примеры:

• Неполная документация API
• Устаревшие руководства
• Отсутствующие примеры кода
• Опечатки в документации

---

Отчёт об ошибке

Шаблон отчёта об ошибке

## Описание
Краткое четкое описание ошибки.

## Шаги для воспроизведения
1. Первый шаг
2. Второй шаг
3. Третий шаг

## Ожидаемое поведение
Что должно происходить.

## Фактическое поведение
Что происходит на самом деле.

## Окружение
- Версия XOOPS: X.Y.Z
- Версия PHP: 8.2/8.3/8.4
- База данных: MySQL/MariaDB версия
- Операционная система: Windows/macOS/Linux
- Браузер: Chrome/Firefox/Safari

## Скриншоты
Если применимо, добавьте скриншоты, показывающие проблему.

## Дополнительный контекст
Любая другая релевантная информация.

## Возможное исправление
Если у вас есть предложения по исправлению проблемы (опционально).

Хороший пример отчёта об ошибке

## Описание
Страница входа показывает пустую страницу при отказе соединения с базой данных.

## Шаги для воспроизведения
1. Остановите сервис MySQL
2. Перейдите на страницу входа
3. Наблюдайте поведение

## Ожидаемое поведение
Показать дружественное сообщение об ошибке, объясняющее проблему соединения с базой данных.

## Фактическое поведение
Страница полностью пуста - нет сообщения об ошибке, нет интерфейса.

## Окружение
- Версия XOOPS: 2.7.0
- Версия PHP: 8.0.28
- База данных: MySQL 5.7
- Операционная система: Ubuntu 20.04
- Браузер: Chrome 120

## Дополнительный контекст
Это может влиять на другие страницы тоже. Ошибка должна отображаться администраторам или регистрироваться надлежащим образом.

## Возможное исправление
Проверьте соединение с базой данных в header.php перед отрисовкой шаблона.

Плохой пример отчёта об ошибке

## Описание
Вход не работает

## Шаги для воспроизведения
Это не работает

## Ожидаемое поведение
Должно работать

## Фактическое поведение
Не работает

## Окружение
Последняя версия

---

Отчёт о предложении функции

Шаблон предложения функции

## Описание
Четкое, краткое описание функции.

## Формулировка проблемы
Почему нужна эта функция? Какую проблему она решает?

## Предложенное решение
Опишите идеальную реализацию или UX.

## Рассмотренные альтернативы
Есть ли другие способы достичь эту цель?

## Дополнительный контекст
Любые макеты, примеры или ссылки.

## Ожидаемое влияние
Как это будет полезно пользователям? Это будет нарушающим изменением?

Хороший пример предложения функции

## Описание
Добавить двухфакторную аутентификацию (2FA) для учетных записей пользователей.

## Формулировка проблемы
С увеличением количества нарушений безопасности многие платформы CMS теперь предлагают 2FA. Пользователи XOOPS хотят более сильную безопасность учетных записей помимо паролей.

## Предложенное решение
Реализовать 2FA на основе TOTP (совместимо с Google Authenticator, Authy и т.д.).
- Пользователи могут включить 2FA в своем профиле
- Отображение QR-кода для установки
- Генерация резервных кодов для восстановления
- Требовать код 2FA при входе

## Рассмотренные альтернативы
- 2FA на основе SMS (требует интеграции оператора, менее безопасно)
- Аппаратные ключи (слишком сложно для обычных пользователей)

## Дополнительный контекст
Похоже на реализации в GitHub, GitLab и WordPress.
Ссылка: [TOTP Standard RFC 6238](https://tools.ietf.org/html/rfc6238)

## Ожидаемое влияние
Увеличивает безопасность учетной записи. Может быть опциональной изначально, обязательной в будущих версиях.

---

Проблемы безопасности

НЕ сообщайте публично

Никогда не создавайте публичный отчёт о уязвимостях безопасности.

Сообщите приватно

1. Отправьте команде безопасности: security@xoops.org
2. Включите:
   • Описание уязвимости
   • Шаги для воспроизведения
   • Потенциальное воздействие
   • Вашу контактную информацию

Ответственное раскрытие

• Мы подтвердим получение в течение 48 часов
• Мы будем предоставлять обновления каждые 7 дней
• Мы будем работать над сроком исправления
• Вы можете запросить признание за открытие
• Координировать время публичного раскрытия

Пример проблемы безопасности

Тема: [SECURITY] Уязвимость XSS в форме комментариев

Описание:
Форма комментариев в модуле Publisher не правильно экранирует введенные пользователем данные,
позволяя атаки хранилища XSS.

Шаги для воспроизведения:
1. Создайте комментарий с: <img src=x onerror="alert('xss')">
2. Отправьте форму
3. JavaScript выполнится при просмотре комментария

Воздействие:
Злоумышленники могут украсть токены сеанса пользователя, выполнять действия от имени пользователей,
или дефэйсить веб-сайт.

Окружение:
- XOOPS 2.7.0
- Модуль Publisher 1.x

---

Лучшие практики названия ошибки

Хорошие названия

✅ Страница входа показывает пустую ошибку при отказе соединения с БД
✅ Добавить поддержку двухфакторной аутентификации
✅ Валидация формы не предотвращает SQL-инъекцию в поле name
✅ Улучшить производительность запроса списка пользователей
✅ Обновить документацию установки для PHP 8.2

Плохие названия

❌ Ошибка в системе
❌ Помогите мне!!
❌ Это не работает
❌ Вопрос о XOOPS
❌ Ошибка

Рекомендации по названию

• Будьте конкретны - Упомяните что и где
• Будьте кратким - Менее 75 символов
• Используйте настоящее время - “показывает пустую страницу” а не “показывала”
• Включите контекст - “в административной панели”, “во время установки”
• Избегайте универсальных слов - Не “исправить”, “помочь”, “проблема”

---

Лучшие практики описания ошибки

Включите основную информацию

1. Что - Четкое описание проблемы
2. Где - Какая страница, модуль или функция
3. Когда - Шаги для воспроизведения
4. Окружение - Версия, ОС, браузер, PHP
5. Почему - Почему это важно

Используйте форматирование кода

Сообщение об ошибке: `Error: Cannot find user`

Фрагмент кода:
```php
$user = $this->getUser($id);
if (!$user) {
    echo "Error: Cannot find user";
}

### Включите скриншоты

Для проблем UI включите:
- Скриншот проблемы
- Скриншот ожидаемого поведения
- Аннотируйте, что не так (стрелки, круги)

### Используйте теги

Добавьте теги для категоризации:
- `bug` - Отчёт об ошибке
- `enhancement` - Запрос улучшения
- `documentation` - Проблема документации
- `help wanted` - Ищем помощь
- `good first issue` - Хорошо для новых участников

---

## После отправки отчёта

### Будьте отзывчивы

- Проверьте комментарии в отчёте
- Предоставьте дополнительную информацию при запросе
- Протестируйте предложенные исправления
- Проверьте, существует ли ошибка в новых версиях

### Следуйте этикету

- Будьте уважительны и профессиональны
- Предположите добрые намерения
- Не требуйте исправлений - разработчики - волонтеры
- Предложите помочь, если возможно
- Поблагодарите участников за их работу

### Держите отчёт в фокусе

- Оставайтесь в теме
- Не обсуждайте несвязанные ошибки
- Ссылайтесь на связанные ошибки вместо этого
- Не используйте ошибки для голосования за функции

---

## Что происходит с ошибками

### Процесс сортировки

1. **Создана новая ошибка** - GitHub уведомляет сопровождающих
2. **Начальный просмотр** - Проверена четкость и дубликаты
3. **Назначение тега** - Категоризирована и приоритизирована
4. **Назначение** - Назначена кому-либо при необходимости
5. **Обсуждение** - Собрана дополнительная информация при необходимости

### Уровни приоритета

- **Критично** - Потеря данных, безопасность, полный отказ
- **Высоко** - Сломана основная функция, влияет на многих пользователей
- **Среднее** - Часть функции сломана, есть обходное решение
- **Низко** - Незначительная проблема, косметическая, или нишевое использование

### Результаты разрешения

- **Исправлено** - Ошибка разрешена в PR
- **Не будет исправляться** - Отклонено по техническим или стратегическим причинам
- **Дубликат** - То же самое, что другая ошибка
- **Недействительна** - На самом деле не ошибка
- **Нужна дополнительная информация** - Ожидание дополнительных деталей

---

## Примеры ошибок

### Пример: Хороший отчёт об ошибке

```markdown
## Описание
Администраторы не могут удалять элементы при использовании MySQL со строгим режимом включенным.

## Шаги для воспроизведения
1. Включить `sql_mode='STRICT_TRANS_TABLES'` в MySQL
2. Перейти в административную панель Publisher
3. Нажать кнопку удаления на любой статье
4. Показана ошибка

## Ожидаемое поведение
Статья должна быть удалена или показать значимую ошибку.

## Фактическое поведение
Ошибка: "SQL Error - Unknown column 'deleted_at' in ON clause"

## Окружение
- Версия XOOPS: 2.7.0
- Версия PHP: 8.2.0
- База данных: MySQL 8.0.32 с STRICT_TRANS_TABLES
- Операционная система: Ubuntu 22.04
- Браузер: Firefox 120

## Скриншоты
[Скриншот сообщения об ошибке]

## Дополнительный контекст
Это происходит только со строгим режимом SQL. Работает нормально с параметрами по умолчанию.
Запрос находится в классе class/PublisherItem.php:248

## Возможное исправление
Используйте одинарные кавычки вокруг 'deleted_at' или используйте обратные кавычки для всех имен столбцов.

Пример: Хороший запрос функции

## Описание
Добавить конечные точки REST API для доступа только чтения к публичному контенту.

## Формулировка проблемы
Разработчики хотят создавать мобильные приложения и внешние сервисы, используя данные XOOPS.
Сейчас ограничено API SOAP, который устарел и плохо задокументирован.

## Предложенное решение
Реализовать RESTful API с:
- Конечными точками для статей, пользователей, комментариев (только чтение)
- Аутентификация на основе токена
- Стандартные коды состояния HTTP и ошибки
- Документация OpenAPI/Swagger
- Поддержка пагинации

## Рассмотренные альтернативы
- Улучшенный API SOAP (устаревший, не совместимый со стандартами)
- GraphQL (более сложный, может быть в будущем)

## Дополнительный контекст
См. рефакторинг API модуля Publisher для похожих паттернов.
Будет согласоваться с современной веб-разработкой.

## Ожидаемое влияние
Включить экосистему сторонних инструментов и мобильных приложений.
Улучшит принятие XOOPS и экосистему.

---

Связанная документация

• Кодекс поведения
• Рабочий процесс разработки
• Рекомендации по pull request
• Обзор взносов

---

#xoops #issues #bug-reporting #feature-requests #github