Гайд, как зарепортить проблему, чтобы вас не возненавидели
За 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 - а то это еще большая проблема...
