Гайд, как зарепортить проблему, чтобы вас не возненавидели

За 3 года я закрыл ~500 issue. Какие-то сразу, какие-то висят месяцами и годами. Некоторых авторов я вообще хочу забанить на GitHub. Разница между всеми Issue не в сложности бага, а в том, как они оформлены.

Мой личный топ абсурда:
🥇Issue с заголовком clone https://github.com/... cd ... и пустым телом. Совсем пустым. А в комментах автор спрашивает: «What features does it entail?» - то есть что должен делать его собственный issue, человек уточняет у меня.
🥈Заголовок 2actions / windows2015beta @ mystery file playground.., внутри кусок CI-конфига вперемешку с обрывками HTML-таблицы. Я до сих пор не знаю, о чем это было.

Если серьезно, самая частая проблема - недостаток информации. Чтобы просто ПОНЯТЬ, что у человека сломалось, нужно три раунда переписки с таймзоной в 12 часов. Вот тебе и пара недель до фикса.

Вот антипаттерны, после которых Issue зависает:

- "Не работает" Нет версии, нет трейсбека, нет кода. Вот в таком виде: "у меня NATS в k8s, под упал - faststream завис". Всё, два предложения. Я не экстрасенс - первый ответ всегда будет "приложите код".

- Нужны версии ВСЕХ (важных) библиотек: вот issue, где код приложили, а версию pydantic - нет. Дело оказалось именно в ней. Минус раунд переписки на ровном месте

- "Минимальный пример" на 200 строк. Внутри ваш бизнес-код, конфиги и три лишние зависимости. Чем больше кода - тем дольше искать, что сломалось. И тем больше мне впадлу это делать. Попробуйте-ка разобрать вот эту простыню

- Баг, который на самом деле вопрос. "Как сделать X?" - это discussions, а не issue. А лучше вообще в чате спросить, там ответят быстрее. В т.ч. и другие пользователи. Половина таких закрывается одной ссылкой на доку в тот же день.

- Фича-реквест без юзкейса. "Добавьте X" - зачем? Опишите задачу, а не решение: возможно, нужное уже есть, просто называется иначе. Вот реквест на manual commit в Kafka - опять же просто ссылка на доку (я вам что, Google? ChatGPT?)

- "В проде падает". Окей. Версия библиотеки? Python? Брокера? Код? Трейсбек ошибки? Прода у меня нет, у меня есть только то, что вы написали.

А вот чеклист issue, который решается за 5 минут:

1️⃣ Версии - библиотеки, Python, брокера/окружения. Если ошибка в конкретной подбиблиотеке - укажите её версию тоже.
2️⃣ Минимальный пример - код, который воспроизводит проблему копипастом. Реально минимальный: 10-20 строк без вашего домена. Даже если вашу проблему понятно как воспроизвести - ПРИЛОЖИТЕ, СУКА, КОД. Дело в том, что я трубу шатал вашу проблему воспроизводить - а вот ctrl+c ctrl+v нажать способен. Пример
3️⃣ Полный traceback - не скриншот и не последняя строчка
4️⃣ Что уже пробовал - чтобы не советовали то, что вы уже отмели
5️⃣ Для фич: юзкейс вместо решения. Опишите, какую задачу решаете, а не что мне делать. Это я уже сам придумаю.

Так выглядит идеальный issue: минимальный пример на 8 строк, шаги воспроизведения, "ожидал X - получил Y". Закрыт без единого уточняющего вопроса.

Такой issue можно решить за 5 минут, потому что понятно, что сломалось и что делать. И это работает с любым проектом, не только моим: хорошо написанный issue - это самый дешевый способ получить бесплатную помощь от самого компетентного человека в этом коде.

Сохраните себе и отправляйте коллеге, когда он пишет "не работает, помогите"🌚

В следующий раз закину примеры по PR - а то это еще большая проблема...

#opensource #программирование