Репозиторій і коміти: як читати сторінку репозиторію

У продуктовій команді Котокорму майже все починається з github.com/catchow/website. Репозиторій на GitHub — це файли одного проєкту з усією історією їхніх комітів, а довкола них issues, pull requests і релізи команди. Читай його сторінку як газету, згори донизу; кнопки інколи переїжджають, але частини лишаються ті самі.

На самій горі — власник і назва, catchow / website, і позначка Private: репозиторій бачить лише команда. Праворуч три кнопки:

• Watch керує сповіщеннями. Рівень вибираєш сам: All Activity, лише обговорення, де ти береш участь чи тебе згадали, або Custom, де можна позначити тільки релізи чи pull requests.
• Star — закладка й публічне «мені подобається». Без сповіщень.
• Fork створює власну копію репозиторію, тобто форк. Це важливо для open-source-проєктів; у своїй компанії він рідко знадобиться.

Продакту найкорисніший Watch із Custom: релізи й pull requests без шуму від кожного коментаря.

Вкладка Code на сторінці репозиторію побудована від загального до конкретного, і кожна частина відповідає на своє питання.

1. Шапка: власник, назва й кнопки Watch, Fork, Star. Чий це проєкт?
2. Вкладки: Code (де ти зараз), Issues (баги й задачі), Pull requests (запропоновані зміни), Actions (автоматичні перевірки й збірки), Projects (дошки). Де обговорюють роботу?
3. Перемикач гілок з main і лічильниками гілок і тегів. Яку версію файлів я бачу? Файли нижче завжди належать вибраній гілці.
4. Смужка останнього коміту: автор, повідомлення, короткий хеш, «3 days ago», а праворуч лічильник на кшталт 412 Commits, що відкриває всю історію. Що сталося останнім?
5. Список файлів: папки й файли, кожен із повідомленням останнього коміту, що його зачепив, і часом.
6. README під списком: вступ до проєкту від самої команди.

Коли знаєш порядок, перевантажена сторінка стає швидким оглядом: глянь на останній коміт, перевір гілку, а тоді йди до потрібного файлу чи вкладки.

Де живе ціна доставки Котокорму? Подивись на рядки списку файлів. Кожна папка й файл мають дві додаткові колонки: повідомлення останнього коміту, що їх зачепив, і як давно це було.

Тож біля config/ написано «Raise delivery price to 59 UAH · 3 weeks ago», а біля pages/ — «Add summer promo banner · 3 days ago». Нічого не відкриваючи, видно, які куточки проєкту нещодавно змінювалися, а які стоять тихо місяцями. Тому список файлів — зручна мапа, коли питають: «що останнім часом змінилося на сайті?»

Пам'ятай, чим ця колонка не є. Вона показує лише останню зміну, а не першу: папка може існувати роками, і її могли зачепити десятки комітів. Щоб побачити все, що колись відбувалося з файлом, відкривають його історію (кнопка History на сторінці файлу) — це тема наступного уроку.

Натисни саме повідомлення, і відкриється сторінка цього коміту з автором, хешем і diff.

Кожна частина сторінки репозиторію відповідає на одне питання, і якщо знаєш, на яке, — заощадиш багато кліків.

• Перемикач гілок з main каже, яку версію файлів ти бачиш. Перемкни на іншу гілку — і список файлів зміниться разом із нею.
• Лічильник комітів, наприклад 412 Commits, — посилання на всю історію цієї гілки, найновіші вгорі.
• Рядок файлу на кшталт «Fix typo in footer · 2 months ago» показує останній коміт, що змінив цей файл, і коли.
• README — вступ команди до проєкту: що це, як запустити, кого питати. Добрий README — перше, що варто прочитати в незнайомому репозиторії.
• Вкладка Pull requests містить запропоновані зміни, які обговорюють і переглядають, перш ніж вони потраплять у main; вкладка Issues — баги й задачі.

Коли стейкхолдер щось питає, зістав питання з частиною: «що зараз на сайті?» — це main, «що змінилося?» — історія, «що готується?» — pull requests.

Клацати по папках зручно, коли знаєш, де шукати. Коли не знаєш, на GitHub є два інструменти пошуку, і шукають вони різне.

Go to file — кнопка над списком файлів (або клавіша t) — шукає файли за назвою. Вводиш «delivery» і бачиш усі файли з цим словом у шляху, як-от pages/delivery.html чи config/delivery.json.

Поле пошуку на самій горі GitHub шукає всередині файлів. На сторінці репозиторію воно пропонує шукати лише в ньому й додає до запиту repo:catchow/website. Візьми точну фразу в лапки, наприклад repo:catchow/website "Free delivery from 800 UAH", і отримаєш файл і рядок, де вона є.

Так розробники знаходять тексти, які просить змінити маркетинг: шукати швидше, ніж пам'ятати структуру папок, навіть тим, хто її створював. Для продакта чи маркетолога це найкоротший шлях від «на сайті написано X» до «X живе в цьому файлі, останній коміт — ось цей».

Коміт — це один збережений крок в історії: набір змін з автором, датою, повідомленням і унікальним хешем. Натисни на повідомлення в рядку config/, і відкриється сторінка коміту a41c09e.

Читай її згори донизу. Спершу повідомлення, далі автор і «committed 3 weeks ago». Праворуч — батьківський коміт (крок, на якому цей збудовано) і хеш: на сторінці видно сім символів, але повний хеш має 40, і обидва вказують на той самий коміт. Нижче — підсумок на кшталт «Showing 1 changed file with 1 addition and 1 deletion» і змінені рядки червоним і зеленим, тобто diff.

Пошукай другий рядок у повідомленні. Тут він каже: «Courier rates went up on 1 June; finance asked to pass it on. (#128)». Це #128 веде на pull request, де зміну обговорювали, тож коміт разом із PR зазвичай розповідає всю історію. Чого на сторінці коміту немає: списку гілок і нічого про клієнтів, наприклад скільки людей побачили зміну.

Перемикач гілок рахує ще й теги. Тег (tag) прикріплює постійну назву до одного коміту, зазвичай версію. Коли Котокорм робить реліз, команда ставить тег на коміт, що пішов на сайт, наприклад v2.4.0.

Ключова думка: коміт — це знімок усього проєкту в певний момент, а не лише змінених рядків. Тож позначений тегом коміт несе в собі всю попередню роботу. В історії на кшталт цієї:

• c1 «Add wishlist button»
• c2 «Fix cart total on mobile»
• c3 «Add gift cards» ← v1.8.0
• c4 «Change hero image»
• c5 «Add product ratings»

реліз v1.8.0 містить c1, c2 і c3. Коміти після тегу, c4 і c5, уже є в main, але не в цій версії; вони підуть у наступний реліз.

Це корисно, коли клієнт каже: «у v1.8.0 подарункові картки вже були, а рейтингів ще ні». Знайди тег — і все, що на наших схемах вище (тобто старіше), входить у цю версію.

Версію легко уявити як заморожену копію сайту, що лежить у шухляді. У Git усе значно легше: тег — це лише назва, прикріплена до одного наявного коміту. Жодні файли не копіюються. Оскільки кожен коміт уже є знімком усього проєкту, назви досить, щоб сказати: «саме цей стан — версія 2.4.0».

У перемикачі гілок теги й гілки схожі, але поводяться по-різному. Гілка рухається: кожен новий коміт у main несе назву гілки вперед. Тег стоїть на місці: v2.4.0 назавжди вказує на той самий коміт, а саме цього й чекаєш від версії.

Розробники створюють тег командою git tag v2.4.0 і надсилають його на GitHub через git push origin v2.4.0. На GitHub реліз зазвичай будують на тезі й додають до нього нотатки й файли для завантаження; релізи ти читатимеш у модулі 4.

Для продакта тег відповідає на точне питання: «що саме було у версії, яку мав клієнт?» Відкрий тег — і побачиш файли такими, якими вони були тоді.

Коміт «Raise delivery price to 59 UAH» від Daniel, веброзробника Котокорму, відповів на питання підтримки за секунди. Добрі повідомлення комітів тримаються кількох звичок:

• Короткий підсумковий рядок, десь 50 символів, у формі наказу: «Fix», «Add», «Raise». Перевір його, продовживши речення «If applied, this commit will…».
• Конкретні слова: «Raise free-delivery threshold to 1000 UAH», а не «Update prices».
• Якщо причина неочевидна — порожній рядок, а далі навіщо: яку проблему розв'язує, хто просив. Diff і так показує, що змінилося; пояснити навіщо може лише повідомлення.
• Один коміт — одна ідея. Якщо в підсумку тричі трапляється «and», це мало бути три коміти. Малі коміти легше читати, перевіряти й відкочувати.

Повідомлення на кшталт «fix», «changes» чи «stuff after the meeting» забирають час у наступного читача, а наступним читачем часто виявляєшся ти сам — через пів року, коли пояснюєш фінвідділу якусь цифру. Ті самі звички роблять зрозумілою і назву pull request.