Баг-репорт і GitHub issues: шаблони, мітки й майлстоуни

У Котокормі робота над лояльністю розповзлася по чатах, трьох pull requests і одному issue, яке CEO назвав «Loyalty» й описав одним рядком: «Need this before Black Friday!!». Новий колега ніколи не знайшов би все це разом.

Issue — це місце на GitHub для всього, про що команда має знати або що має зробити. Більшість issues належать до трьох видів: баг-репорт (щось зламалося), запит на фічу (чогось бракує) і задача (справа з відповідальним і часто з датою). Issue зазвичай з'являється раніше за код, і читають його люди, яких не було на нараді, тож воно має бути зрозумілим без пояснень.

Код, який відповідає на issue, приходить пізніше як pull request із посиланням на нього. Issue — це запитання, pull request — одна з відповідей. Pull request можна відкрити й без issue, але за місяць ніхто не згадає, яку проблему він розв'язував. Закрите issue теж зберігає причину: закрито як виконане або закрито як незаплановане.

Розробник може виправити лише те, що здатен відтворити на своєму екрані. Добрий баг-репорт дає йому чотири речі.

• Кроки, щоб відтворити: що робити й у якому порядку, починаючи з відомого стану (який акаунт, який флаг увімкнено).
• Очікуваний результат: що мало статися.
• Фактичний результат: що сталося натомість.
• Де: пристрій, браузер, акаунт, номер замовлення, а якщо є — скриншот.

Issue #159 у Котокормі зроблено саме так. З акаунта працівника замовляють товари на 600 грн, застосовують промокод на 100 грн і платять 500 грн. Очікувано: 50 балів, по одному за кожні 10 грн оплати. Фактично: 60 балів, пораховані до знижки. Будь-хто повторить це за дві хвилини, а два числа одразу показують розбіжність.

Назва описує симптом, а не емоцію: «Points counted before promo discount», а не «Points broken». Двом речам у репорті не місце. Терміновість узгоджують із командою, а не пишуть великими літерами. А шукати файл із помилкою — робота розробника; здогадка автора репорту лише збиває з пантелику.

Запит на фічу відповідає на три запитання для тих, кого не було на нараді: чого хочуть, навіщо це і як зрозуміти, що роботу зроблено. У корисному запиті є:

• назва, що описує результат, а не тему: «Customers can reuse a saved delivery address», а не «Addresses»;
• кілька рядків контексту: у кого проблема і чого вона їм коштує;
• критерії приймання: перевірки, які мають справджуватися, коли роботу завершено, сформульовані так, щоб людина могла їх перевірити;
• що не входить у межі, щоб робота непомітно не розросталася.

GitHub може підштовхнути всіх до такого формату через шаблони issues: файли в папці .github/ISSUE_TEMPLATE/ репозиторію. Після цього New issue спершу питає, що саме відкрити, наприклад «Bug report» чи «Feature request», і заповнює заголовки й мітки; шаблон бага може сам додати мітку bug. Є й версія-форма з окремими полями, і деякі з них можна зробити обов'язковими.

Пам'ятай про межу: шаблон може вимагати поле, але не добру відповідь. Заповнити його добре — все одно завдання автора.

Бокова панель праворуч від issue має ті самі поля, що й pull request, і кожне відповідає на одне з повсякденних запитань продакта.

• Labels (мітки) кажуть, що це за робота і якої частини продукту стосується: bug, content, loyalty. Відфільтруй список issues за label:loyalty, і вся програма поміститься на одному екрані.
• Assignees (виконавці) — ті, хто відповідає за те, щоб issue рухалося. Це не обов'язково автор: продакт пише баг #159, а виконавцем призначають розробника Daniel. Призначити можна кількох людей, але одне ім'я одразу показує, кого питати.
• Milestone прив'язує issue до цілі з датою.
• Development показує гілки й pull requests, які над ним працюють.

Міток має бути мало, і кожна має щось означати. Якщо на кожному issue по шість міток, фільтр за будь-якою нічого не скаже, і ними перестануть користуватися. Невеликого узгодженого набору (тип роботи плюс частина продукту) більшості команд досить.

Деяка робота завелика для одного issue. Програмі лояльності Котокорму потрібні виправлення бага, баланс у кабінеті, списання балів під час оформлення, сторінка програми й перемикач запуску. Десять не пов'язаних між собою issues знову все розпорошать, а один величезний опис сховає, хто що робить.

Рішення — батьківське issue із sub-issues. У батьківському — мета й те, що означає «запущено»: #147 перейменовують на «Launch loyalty points before Black Friday». Кожне sub-issue — звичайне issue, прикріплене до нього, з власним номером, виконавцем, мітками й станом, тож Daniel може закрити свою частину, не чіпаючи чужих. Батьківське issue показує їх списком і рахує прогрес, наприклад «закрито 1 з 4».

У старіших репозиторіях роблять щось схоже чеклистом в описі: рядки, що починаються з - [ ], показуються як прапорці. Це працює, але їх ставлять вручну, а в рядка чеклиста немає власного виконавця чи стану. Sub-issues — це ті частини, які люди справді беруть у роботу.

Майлстоун об'єднує issues і pull requests під однією метою, з необов'язковим дедлайном і смугою прогресу. Мітки відповідають на запитання «що це за робота?», а майлстоун — «до чого ми йдемо і до коли?». Майлстоун Котокорму «Loyalty launch» має дедлайн 13 листопада, за два тижні до Black Friday, і містить батьківське #147, його sub-issues і pull requests лояльності.

Смуга — проста арифметика: закриті елементи ÷ усі елементи. Змерджений pull request рахується як закритий. Так само й issue, закрите як незаплановане: відкинута ідея рухає смугу так само, як завершена робота. Коли закрито 2 елементи з 8, «Loyalty launch» показує 25%.

Через це відсоток легко прочитати неправильно. Він рахує елементи, а не зусилля: виправлення одного рядка тексту і вся зміна оформлення замовлення важать однаково. І половинок у ньому немає: відкритий pull request просто відкритий. Перш ніж звітувати про прогрес, прочитай список під смугою: що ще відкрито, наскільки воно велике і чи не закрито щось як відкинуте замість зробленого.

Робота над issue може початися з самого issue. У розділі Development є Create a branch: GitHub пропонує назву з номера й заголовка issue, а Daniel змінює її за звичкою команди на fix/points-after-discount. Відтак issue показує цю гілку, а згодом і її pull request.

В описі pull request два посилання схожі на вигляд, але поводяться по-різному:

• Fixes #159 містить ключове слово закриття. Коли pull request змерджать в основну гілку (main), GitHub закриє #159 як виконане. Ключові слова — close, fix і resolve з їхніми звичними закінченнями: closes, closed, fixes, fixed, resolves, resolved.
• Part of #147 — проста згадка. У хронології #147 з'явиться позначка, що pull request на нього посилався, і нічого не закриється. «Related to» чи «See» працюють так само.

Саме тому частина великої програми ніколи не пише Fixes #147: перший змерджений шматок закрив би все батьківське issue. Закривай своє sub-issue, батьківське лише згадуй.

У ключових слів закриття є два правила, на яких часто спотикаються.

Одне ключове слово на кожен номер. Fixes #162 and #163 закриє лише #162; #163 отримає згадку й лишиться відкритим. Щоб закрити обидва, повтори ключове слово: Fixes #162, fixes #163. А батьківське issue додай простою згадкою, Part of #147, щоб ця частина з'явилася в хронології програми, але не закрила її.

Нічого не закривається до мерджу. Відкритий pull request із Fixes #159 лише пов'язує їх; issue закриється, коли pull request змерджать в основну гілку, у Котокормі це main. Pull request, змерджений в іншу гілку, нічого не закриває. Ті самі ключові слова працюють і в повідомленні коміту, щойно цей коміт потрапить в основну гілку.

Після мерджу issue отримує фіолетову позначку «закрито як виконане», а розділ Development зберігає посилання на pull request, тож будь-хто бачить, що його закрило і коли. Якщо виправлення не спрацювало, issue можна відкрити знову, а не заводити нове.

Коли змерджено #165, pull request від Daniel з Fixes #159 для бага з балами, #159 закривається само й отримує фіолетову позначку: закрито як виконане. У Котокормі мердж у main викладають за кілька хвилин, і тест працівників після обіду проходить: оплачено 500 грн, нараховано 50 балів. Баг виправлено в робочому коді.

Але клієнти досі не бачать жодних балів. Програма схована за фіча-флагом loyalty-points, а він увімкнений лише для працівників. Стан issue і флаг відповідають на різні запитання:

• Стан issue (відкрите, закрите як виконане, закрите як незаплановане): чи зроблено роботу?
• Деплой: чи працює код на сайті?
• Фіча-флаг: хто бачить фічу?

Тримай ці три речі окремо, коли звітуєш підтримці, продажам чи CEO. «#159 закрито» — правда, але вона вводить в оману, якщо слухач почує «клієнти тепер отримують правильні бали». Кажи, що вже працює, хто це бачить і коли це зміниться. А сторінка релізу — лише опис змін; її публікація нічого не викладає.