Как написать хороший issue

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

В тот год я также узнал, что написание issue — это важная форма общения. Для контрибьютора это может быть ценным навыком, который стоит развивать для создания хороших отношений и поддержки мейнтейнеров.

Если вы пытаетесь участвовать в работе с открытым исходным кодом, один из способов начать — это писать ишью, в которых сообщается об ошибках, запрашиваются функции или предлагаются улучшения.

От редакции Techrocks: также предлагаем почитать «Участие в Open Source: полное руководство».

Зачем нужны issue?

Issue часто являются отправной точкой для коммуникации. С их помощью контрибьютор может сообщить о чем-то мейнтейнерам, а мейнтейнер — сообщить контрибьюторам о каких-то нуждах.

Обычно в каждом ишью есть одна основная идея с объяснением. Например, баг-репорт касается одного бага, а просьба расширить функциональность описывает одну функцию.

Элементы хорошего issue

Хороший issue должен содержать несколько ключевых элементов, которые помогают четко и ясно сообщить о проблеме или внести предложение:

Четкое и лаконичное название. Заголовок должен описывать проблему так, чтобы ее было легко понять.
Подробное описание. Описание должно включать подробное объяснение проблемы. Важно использовать четкий и лаконичный язык, быть конкретным, избегать предположений, расплывчатых или двусмысленных формулировок, быть уважительным и профессиональным. При необходимости нужно предоставить дополнительную информацию, чтобы прояснить проблему.
Наглядность. Скриншоты, гифки, видео и прочие визуальные материалы могут быть полезны для иллюстрации проблемы.
Контекстная информация. Предоставьте любую дополнительную информацию о среде или системе, которых касается ишью.
Предлагаемое решение. Если у вас есть идея, как решить проблему, изложите ее в issue.

Элементы хорошего баг-репорта

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

Шаги по воспроизведению бага
Ваша рабочая среда (операционная система и т.д.)
Используемый вами браузер
Любые подходящие скриншоты, видео, код или контекст.

Элементы хорошего запроса на функциональность

В запросе на функциональность вы должны помочь мейнтейнеру понять, почему эта функция важна. Как правило, следует включить следующую информацию:

Тип функции (документация, стиль, особенность кода и т.д.).
Текущее состояние приложения и решение, которое вы предлагаете с помощью вашей фичи
Любой дополнительный контекст, включая альтернативные варианты, которые вы рассматривали.

Шаблоны issue

В некоторых репозиториях используются шаблоны issue. Они должны помочь вам в описании проблемы. Например, у нас в OpenSauced есть шаблоны для баг-репортов и запросов функций (см. ниже).

Шаблоны помогают гарантировать, что мейнтейнер получит всю информацию, необходимую для общения с контрибьюторами. Если есть шаблоны, важно использовать их, а не писать issue с нуля.

Пример хорошего issue

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

Четкий и лаконичный заголовок

TypeError: Тело непригодно для использования при использовании Remix(experimental-netlify-edge) Actions

Подробное описание и шаги по воспроизведению бага

В issue Ник описывает некоторые ключевые шаги:

Какую версию Remix он использует
Шаги по воспроизведению, включая нумерованный список, фрагменты кода, скриншоты и ссылку на обсуждение в Discord с более подробным контекстом
Ожидаемое поведение
Фактическое поведение со скриншотом сообщения об ошибке.

Визуальные материалы

В описании issue есть скриншот вида при локальном запуске и в Postman.

Предлагаемое решение

Хотя в первоначальном ишью нет предлагаемого решения, Ник исследует происходящее и поддерживает обсуждение в комментариях. В рамках исследования он создал репозиторий, чтобы помочь мейнтейнерам, и поделился своим подходом в комментарии.

Рабочая среда

Ник сообщил версию Remix, версии Node, которые он пробовал, и указал, что был установлен Netlify CLI.

Обсуждение

Ник не покончил с issue, отправив баг-репорт. Прокрутив страницу, вы увидите, что он продолжил разговор, ссылаясь на беседу в Discord, а также на свое расследование ошибки и ее решения. Он вносит обновления по мере нахождения дополнительной информации, предоставляя фрагменты кода для контекстуализации, и тегает мейнтейнеров, а также других людей, которые участвуют в разработке.

И, как вишенка на торте, — благодарность члену команды, который помог с исправлением.

От редакции Techrocks: также предлагаем почитать:

Написание хороших issue — это важная часть эффективной коммуникации. При этом важно не только создать issue, но и участвовать в решении поднятого вопроса. Это отличный способ продемонстрировать свои навыки общения и проведения расследований.

Перевод статьи «How to Write a Good Issue: Tips for Effective Communication in Open Source».

[customscript]techrocks_custom_after_post_html[/customscript]

[customscript]techrocks_custom_script[/customscript]

Как написать хороший issue

Зачем нужны issue?