Issues на GitHub

Issue: задача или ошибка

Issue на GitHub — это карточка задачи, идеи или ошибки в репозитории: у неё есть номер, заголовок, описание, комментарии, метки и исполнитель. В уроке вы заведёте issue для проекта «Визитка», сделаете по ней pull request и увидите, как карточка закрывается без вашего участия.

В прошлом уроке вы разбирали, как проверять чужие изменения. Но кто решает, что вообще менять? В команде задачи не держат в голове и не пересылают в мессенджерах: их записывают в issues, а потом закрывают pull request-ами.

Простыми словами

Это список дел на холодильнике, только общий: каждая запись пронумерована, к ней можно писать комментарии, назначить исполнителя и вычеркнуть, когда готово. Вычёркивает её, как вы скоро увидите, сам GitHub.

Как создать issue

1. В репозитории откройте вкладку Issues и нажмите New issue. Если в репозитории настроены шаблоны, GitHub предложит выбрать (Get started) либо нажать Open a blank issue: у вас шаблонов нет, поэтому форма откроется сразу.
2. В поле Title напишите короткое название, а в большом поле ниже описание.
3. Если вы владелец репозитория, справа есть настройки: исполнитель (Assignees), метки (Labels), веха (Milestone), проект.
4. Нажмите Submit new issue (надпись в интерфейсе может немного отличаться).

Хорошее описание отвечает на два вопроса: что нужно сделать и как понять, что задача готова.

В разделе «Контакты» есть только почта.
Нужно добавить ссылку на мой профиль GitHub.

Готово, когда: в index.html после строки с почтой появилась
строка «GitHub: alex-ivanov» со ссылкой на профиль.

Номер у issue общий с pull request: если в репозитории уже были PR #1 и #2, новая issue получит номер #3, а следующий PR будет #4. Отдельных счётчиков нет.

Метки (labels)

Метка (label) — цветная пометка на issue. В каждом новом репозитории GitHub уже создаёт набор стандартных меток, вот главные:

Ещё есть duplicate, invalid и wontfix (повтор, неверно, делать не будем). Новую метку добавляют на вкладке Labels кнопкой New label.

Связываем issue с pull request

Самое полезное свойство issues: pull request может закрывать их сам. Для этого в описании PR пишут специальное слово и номер задачи. Когда PR сливают, GitHub закрывает задачу.

Добавил в раздел «Контакты» ссылку на профиль GitHub.

Closes #3

Работают слова close, closes, closed, fix, fixes, fixed, resolve, resolves, resolved. После слова допустим двоеточие, регистр не важен (CLOSES: #3 тоже сработает). Ключевая запись всегда состоит из слова и номера со знаком #.

Слово можно написать и в сообщении коммита. Второй -m в git commit добавляет второй абзац:

$ git commit -m "Добавить ссылку на GitHub в контакты" -m "Closes #3"

Тогда issue закроется, когда этот коммит попадёт в основную ветку. Но PR при этом не появится в списке связанных, поэтому привычнее писать слово в описании PR.

Связать можно и вручную. В правой панели PR есть раздел Development: выберите в нём issue (из того же репозитория), и они окажутся связанными. Обратное тоже возможно: на странице issue нажмите Development, выберите PR и нажмите Apply. Вручную связанную пару можно отвязать, а связь через ключевое слово убирают, стерев слово из описания.

Ссылки и упоминания

GitHub умеет превращать обычный текст в ссылки. Это работает в описаниях и комментариях к issue и PR:

Пользуйтесь ссылками смело: «см. #3» в комментарии лучше, чем пересказ. История проекта сама показывает, откуда что взялось.

Планирование: вехи и проекты

Когда задач много, их группируют. Milestone (веха) объединяет issue в одну цель, например «Версия 1.0», и показывает, сколько из них уже закрыто. Projects — доска с колонками, например «Сделать», «В работе», «Готово». В нашем маленьком проекте обойдёмся без них; достаточно знать, что они есть.

Практика у себя

1. В репозитории alex-ivanov/portfolio (со своим логином) откройте вкладку Issues, нажмите New issue. В Title введите «Добавить ссылку на GitHub в контакты», в описание вставьте образец выше и создайте issue. Если до этого у вас были два PR, она получит номер #3; у вас номер может быть другим, подставляйте свой.
2. Если справа доступны метки, поставьте enhancement.
3. В терминале: git switch main, git pull, git switch -c feature/github-link.
4. В index.html в разделе «Контакты» после строки с почтой добавьте строку из блока ниже.
5. Закоммитьте и отправьте: git add index.html, git commit -m "Добавить ссылку на GitHub в контакты", git push -u origin feature/github-link.
6. На GitHub нажмите Compare & pull request. В описание добавьте строку Closes #3 (с вашим номером), нажмите Create pull request.
7. Посмотрите правую панель PR, раздел Development: там должна быть ваша issue. Если её нет, проверьте запись в описании.
8. Нажмите Merge pull request, Confirm merge, потом Delete branch.
9. Откройте вкладку Issues: issue закрыта (Closed), а внутри неё записано, каким PR.
10. У себя: git switch main, git pull, git branch -d feature/github-link.

    <p>GitHub: <a href="https://github.com/alex-ivanov">alex-ivanov</a></p>

Подставьте свой логин. Строка встаёт сразу под строкой с почтой, внутри <section id="contacts">. Проверка локально:

$ git log --oneline -3
917622a Merge pull request #4 from alex-ivanov/feature/github-link
28c6c68 Добавить ссылку на GitHub в контакты
efda661 Merge pull request #2 from alex-ivanov/feature/about-skills

Проверьте себя

• Issue закрыта автоматически, а внутри неё видно, каким pull request.
• В описании PR записано слово закрытия и номер со знаком #.
• git branch показывает только main, в index.html есть строка со ссылкой на GitHub.
• Вы можете объяснить, почему PR в ветку, отличную от ветки по умолчанию, не закроет задачу.

Частые ошибки

Issue не закрылась после слияния. Проверьте три вещи: слово и номер написаны в описании PR (или в сообщении коммита), у номера есть # (Closes #3, а не Closes 3) и PR сливали в main. Если что-то из этого не так, issue закройте вручную кнопкой на её странице.

Слово закрытия написали только в комментарии. Документация называет два места: описание PR и сообщение коммита. Комментарий под PR в этом списке не значится, не рассчитывайте на него. Допишите слово в описание.

PR сливают в чужую ветку. Если base выбран не main, автозакрытия нет. Исправьте base в заголовке PR или закройте issue вручную.

Закрыли PR без слияния. Закрытие без слияния не закрывает issue: связь срабатывает именно при слиянии.

Что важно запомнить

• Issue — пронумерованная карточка задачи или ошибки; создают её кнопкой New issue, помечают метками и назначают исполнителя.
• Номера у issue и PR общие.
• Closes #3, Fixes #3 или Resolves #3 в описании PR закрывают задачу при слиянии в ветку по умолчанию.
• #3 — ссылка на задачу, @логин — упоминание человека, хеш коммита превращается в ссылку.
• Milestones и Projects помогают планировать, когда задач много.

До сих пор вы работали в своём репозитории, где у вас есть право записи. Но чужие проекты, обычные open source, пустят вас в main только через pull request, да ещё и не напрямую из ветки. Как предложить правку в репозиторий, куда писать нельзя — в следующем уроке.