Хороший issue на GitHub даёт мейнтейнеру всё, что нужно для воспроизведения вашей проблемы, и ничего лишнего. Прежде чем открывать его, поищите среди существующих issue; затем используйте шаблон issue репозитория, напишите конкретный заголовок и приложите минимальный воспроизводимый пример, ваши точные версии и что вы ожидали против того, что произошло на самом деле. Держите одну проблему на один issue, форматируйте его с помощью ограждений кода markdown и будьте терпеливы – большинство мейнтейнеров являются добровольцами. Issue, который можно воспроизвести за две минуты, – это issue, который исправят.
Как Написать Хороший Issue на GitHub: Пошагово
- Сначала поищите среди открытых и закрытых issue. Ваш баг, возможно, уже сообщён, исправлен или объяснён – прокомментируйте там вместо открытия дубликата.
- Проверьте CONTRIBUTING.md и шаблоны issue. Многие проекты направляют вопросы в Discussions и резервируют issue для багов и фич.
- Выберите правильный шаблон и одну проблему. Выберите “bug report” или “feature request” и заводите отдельный issue для каждой отдельной проблемы.
- Напишите конкретный заголовок. Сформулируйте сам симптом, как хорошее сообщение коммита – не “Не работает”.
- Добавьте минимальный воспроизводимый пример. Предоставьте наименьший запускаемый фрагмент, тестовый репозиторий или точные шаги, которые вызывают баг.
- Изложите ожидаемое против фактического поведения и ваше окружение. Укажите точную версию пакета, ОС и среду выполнения, плюс полную ошибку или логи в блоке кода.
- Отправьте, затем оставайтесь на связи. Отвечайте на уточняющие вопросы мейнтейнера, чтобы issue не залежался.
Что Делать и Чего Не Делать
Делайте:
- Ищите среди существующих открытых и закрытых issue перед заведением.
- Следуйте шаблону issue репозитория и руководству для контрибьюторов.
- Пишите один чёткий, конкретный issue на одну проблему.
- Прикладывайте минимальный воспроизводимый пример и точные версии.
- Используйте ограждения кода markdown для кода, логов и стектрейсов.
Не делайте:
- Не открывайте дубликат, не проверив сначала.
- Не заводите расплывчатый issue “не работает” без воспроизведения.
- Не объединяйте несколько несвязанных багов в один issue.
- Не @упоминайте и не пишите мейнтейнерам в личку, требуя быстрого исправления.
- Не плодите комментарии “+1” или “у меня тоже” – вместо этого поставьте реакцию 👍.
Поищите Перед Заведением
Открытые issue – лишь половина картины: поищите и среди закрытых issue. Закрытый issue часто содержит исправление, обходной путь или причину мейнтейнера для “won’t fix”. Если вы нашли подходящий открытый issue, добавьте туда детали своего воспроизведения или окружения вместо открытия дубликата; это консолидирует сигнал, который мейнтейнеры используют для расстановки приоритетов. Используйте поиск issue на GitHub с квалификаторами вроде is:issue текст вашей ошибки, чтобы пробиться сквозь шум.
Используйте Шаблон Issue (И Правильный Канал)
В большинстве зрелых репозиториев поставляются шаблоны issue – форма баг-репорта, форма запроса фичи, иногда опция пустого issue, которую намеренно отключают. Заполняйте шаблон полностью вместо того, чтобы удалять подсказки; каждое поле там потому, что мейнтейнеры устали его выпрашивать.
Прежде чем это сделать, пробегитесь по CONTRIBUTING.md. Многие проекты отправляют вопросы об использовании в GitHub Discussions, на форум сообщества или Stack Overflow и держат трекер issue строго для багов и запросов фич. Публикация вопроса “как сделать” в виде issue в таких репозиториях обычно просто приводит к его закрытию со ссылкой на правильное место.
Сердце Хорошего Issue: Воспроизводимый Пример
Всё остальное вторично по отношению к одному этому вопросу: может ли мейнтейнер воспроизвести вашу проблему? Дайте ему минимальный воспроизводимый пример – наименьший запускаемый фрагмент, тестовый репозиторий или точную последовательность шагов, которая вызывает баг на чистой установке. “Иногда падает” – неактуально; “запуск npm test на свежем клоне этого репро на 15 строк выбрасывает стектрейс ниже” – актуально.
Если вы сообщаете о баге, а не запрашиваете фичу, поместите свой пример прямо в наш шаблон баг-репорта – его поля “Шаги для воспроизведения” и “Окружение” созданы именно для этого.
Укажите Версии и Окружение
“Latest” – это не версия. Укажите точную версию пакета (или SHA коммита), операционную систему и версию языка или среды выполнения – v2.4.1, macOS 14.5, Node 20.11. Баги часто специфичны для версии, и мейнтейнер, который не может понять, на каком релизе вы сидите, потратит обмен сообщениями просто на этот вопрос. Вставьте полное сообщение об ошибке и любые релевантные логи; обрезанная ошибка обычно скрывает ту самую строку, которая действительно важна.
Форматируйте Как Следует
Issue на GitHub – это markdown, так что используйте его. Оборачивайте код, команды и стектрейсы в ограждения из тройных обратных кавычек с подсказкой языка для подсветки синтаксиса. Сворачивайте очень длинные логи внутри блока <details>, чтобы issue оставался читаемым. Обозначайте ключевые части – Ожидаемое, Фактическое, Шаги для воспроизведения – и ссылайтесь на конкретные строки кода пермалинками (нажмите y на GitHub, чтобы получить URL, привязанный к коммиту). Чистый, удобный для просмотра issue сортируется быстрее, чем стена текста.
Помните, Кто на Той Стороне
Большинство мейнтейнеров – неоплачиваемые добровольцы, работающие над проектом в свободное время, и это формирует этикет. Не @упоминайте и не пишите им в личку, требуя исправления, и не добавляйте комментарии “есть апдейты?”, которые только создают шум. Полностью откажитесь от “+1” и “у меня тоже” – поставьте реакцию 👍 на исходный issue, чтобы мейнтейнеры могли оценить спрос без потока уведомлений. Комментируйте только когда у вас есть что-то новое: ещё одно воспроизведение, другое окружение или обходной путь.
И если вы подозреваете уязвимость безопасности, вообще не открывайте публичный issue. Используйте приватное сообщение о безопасности репозитория – обычно это политика SECURITY.md или вкладка GitHub “Report a vulnerability” – чтобы уязвимость не разгласили до того, как её закроют.
Формула По-прежнему Работает
Отличный issue на GitHub – это просто формула Skip The Ask в контексте разработчика:
- Ваша ситуация – проект, версия и окружение, которые вы запускаете
- Ваш конкретный репорт или запрос – точный баг или фича, в чётком заголовке
- Релевантные детали – минимальный воспроизводимый пример, ожидаемое против фактического поведения и полная ошибка
Дайте мейнтейнерам проблему, которую они могут воспроизвести, и вы проделали 90% работы на пути к её исправлению.
Задаёте вопрос “как сделать” вместо сообщения о баге? Наше руководство по Stack Overflow покрывает этот случай. Об универсальных принципах, лежащих в основе каждой платформы, смотрите наше полное руководство по задаванию вопросов онлайн.