Реліз 1.0 і демо-день

Що ти зробиш сьогодні

Теорія

1. Реліз: чим версія відрізняється від чергового коміта

За три місяці в твоєму репозиторії накопичилося кількадесят комітів. Репозиторій (із заняття 03) — це тека, у якій git зберігає всю історію проєкту: кожен збережений стан файлів і порядок, у якому вони змінювалися. У тебе таких тек дві: ~/app, де ти працюєш, і ~/repo.git, куди ти надсилаєш готове. Коміт (теж із заняття 03) — це один збережений стан усіх файлів проєкту з підписом, що саме змінилося. Коміти йдуть один за одним, і серед них є всякі: закінчена робота, половина роботи, виправлення друкарської помилки в коментарі.

Сьогодні з цього ряду треба вибрати один коміт і сказати вголос: ось цей стан ми показуємо людям. Такий вибраний і названий стан називають релізом.

Реліз

Версія програми, яку віддають користувачам. Не будь-який стан коду, а той, про який автор сказав: цей працює, ним можна користуватися.

Версія

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

Приклад із життя. Гра в тебе на телефоні пише «версія 2.14». Розробники за час між попереднім оновленням і цим зробили сотні змін у коді, але користувач бачить один номер і одне речення про те, що нового. Він не читає їхню історію змін по кроках — йому потрібен саме номер.

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

Служба (із заняття 02) — це твоя програма, яку запускає і стежить за нею сама операційна система: після перезавантаження сервера чи після помилки вона запускає програму знову, і тобі не треба щоразу заходити на сервер і запускати її руками. Твоя служба називається club-api — це ім’я їй дав викладач, коли створював тобі акаунт, і воно однакове в усій групі. Керують службою командою systemctl, а прапорець --user у ній означає «моя особиста служба, а не загальносерверна»: чужих служб ти цією командою не бачиш і не чіпаєш.

2. Номер версії: що означає 1.0

Номер версії складається з чисел, розділених крапками. У найпоширенішому порядку їх три: 1.4.2. Кожне число відповідає за свій розмір змін і рахується окремо від сусідніх: після 1.9.0 йде 1.10.0, а не 2.0.0, бо дев’ятка просто зростає до десяти.

Третє число часто не пишуть, поки його нема чим заповнювати. Тому сьогоднішній тег називається v1.0, а не v1.0.0 — так коротше, і сенс той самий: перший реліз, доповнень і виправлень після нього ще не було. Літера v на початку — від слова version, вона нічого не змінює, але за нею одразу видно, що це номер версії, а не якесь інше число.

Приклад із життя. Ти оновив додаток і бачиш «1.4.3, виправлено помилку, через яку додаток закривався сам при відкритті фото». Останнє число зросло на одиницю — можна очікувати, що все на місці й нічого переучувати не доведеться. Якщо ж номер став «2.0», варто прочитати, що там нового: там щось переробили помітно.

3. Тег у git: незмінна позначка на коміті

У кожного коміта є ідентифікатор — рядок виду 9f3c1ab4e7d2... на сорок символів, який git рахує сам. Скорочено пишуть перші сім: 9f3c1ab. Такий рядок неможливо запам’ятати й незручно диктувати. Тому потрібному коміту дають ім’я.

Тег

Ім’я, прив’язане до конкретного коміта. Після git tag v1.0 усюди, де git очікує ідентифікатор коміта, можна писати v1.0.

Головна властивість тега — він не рухається. Порівняй із гілкою. Гілка — це теж ім’я, прив’язане до коміта, але рухоме: у тебе гілка одна, вона називається master і завжди показує на останній коміт. Щойно ти зробиш новий коміт, ім’я master почне показувати вже на нього. Тег v1.0 показуватиме на той самий коміт і завтра, і через рік, скільки б комітів ти не додав після нього. Через це тег і годиться для релізу: за ним завжди знаходиться саме той стан коду, який бачили гості.

Теги бувають двох видів.

Легкий тег

git tag v1.0 — тільки ім’я і нічого більше. Хто поставив і коли, git не збереже.

Анотований тег

git tag -a v1.0 -m "текст" — окрім імені, git запише автора, дату й повідомлення, яке ти дав після -m. Саме такий ми й ставимо: через півроку буде видно, що це за версія і коли вона з’явилася.

Три команди, які знадобляться на практиці:

git tag -a v1.0 -m "Реліз 1.0: перша версія, показана на демо-дні"
git tag -n
git show v1.0

git tag -n друкує список тегів разом із першим рядком повідомлення. git show v1.0 показує сам тег і коміт, на який він вказує: автора, дату, список змінених файлів.

Слово origin у цих командах — не команда git і не гілка, а коротке ім’я, яким твій репозиторій ~/app називає інший репозиторій, куди надсилає роботу. Ти задав його на занятті 03, і показує воно на ~/repo.git. Побачити, куди саме origin веде, можна командою git remote -v.

4. CHANGELOG: перелік змін, написаний для людини

CHANGELOG (читається «ченджлог», від change log — запис змін) — файл, у якому по версіях перелічено, що змінилося в програмі. Лежить у корені репозиторію й називається CHANGELOG.md.

У тебе вже є git log — список усіх комітів. Різниця між ними у тому, для кого вони написані. git log пише про кожен коміт словами того, хто цей код писав: «поправив імпорт», «те саме, але без зайвого запиту». CHANGELOG пише про зміни, які помітив би користувач, і словами, зрозумілими без коду.

Приклад із життя. У магазині додатків під кнопкою «Оновити» є короткий текст «що нового» — це і є CHANGELOG. Ніхто не показує там перелік комітів: він нічого не пояснить людині, яка просто хоче знати, чи полагодили те, що їй заважало.

Як виглядає запис. Кожен рядок — одна зміна, що починається з дієслова: «Додано», «Виправлено», «Прибрано», «Змінено». Порівняй два записи про одне й те саме. У правому стовпці трапляються числа 500 і 422 — це коди відповіді, якими сервер відповідає браузерові на кожен запит. Ти бачив їх на заняттях 05 і 08; коротко: 200 — усе гаразд, сторінку віддано; 404 — за такою адресою нічого немає; 422 — запит дійшов, але дані в ньому не годяться, наприклад порожня назва; 500 — у програмі на сервері сталася помилка, і вона не змогла відповісти.

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

Основні записи ти вже приніс із домашнього завдання заняття 11 — там треба було виписати щонайменше вісім змін, поки деталі ще свіжі в пам’яті. Сьогодні залишається перевірити їх, додати те, що ти зробив уже після здачі того завдання, і поставити зверху заголовок версії.

5. Показ на п’ять хвилин

Демо — це коли ти показуєш працюючий сервіс людям, які його ще не бачили: батькам, друзям, молодшій групі. У тебе рівно п’ять хвилин і хвилина на те, щоб змінити доповідача. Дванадцять людей по шість хвилин — це сімдесят дві хвилини, тобто більша частина сьогоднішнього заняття.

Виступ складається з чотирьох частин у такому порядку.

Кілька порад, які економлять час на показі.

• Код не показуємо. За дві хвилини розібрати main.py не встигнеш, і гостям це нічого не пояснить. Якщо хтось спитає про код — покажеш після виступу.
• Три дії, а не «подивимось, що тут є». Наприклад: відкрити список, додати запис, відмітити його. Ти маєш знати наперед, що з’явиться на екрані після кожного дотику.
• Сторінка вже відкрита в окремій вкладці до початку виступу. Набирати адресу при всіх — це тридцять секунд із трьохсот, які в тебе є.
• Історія поломки — найцікавіша частина для гостей. Вони не оцінять будову програми, але добре зрозуміють розповідь про те, як сервіс перестав відповідати і як ти це виправив. Бери один випадок і розказуй по кроках.

Окрема річ, до якої треба підготуватися: гості користуються сервісом по-справжньому. Це означає, що десяток людей одночасно відкриють твою адресу й почнуть щось додавати. Такого не дасть жоден тест, який ти запускаєш у себе. Тому перед показом потрібні дві речі: свіжа копія бази (раптом хтось додасть двадцять порожніх записів і ти захочеш повернути список до попереднього стану) і відкритий журнал служби в сусідньому вікні терміналу, щоб одразу бачити помилки.

Журнал — це записи, які служба веде про свою роботу: коли запустилася, які запити отримала, на чому зупинилася через помилку. Дивляться його командою journalctl --user -u club-api: --user означає «моя особиста служба», а -u club-api — «журнал саме цієї служби, а не всіх одразу».

Практика

У прикладах — таблиця habit і адреси /api/habits із занять 04 і 05. Підставляй свої назви: вони записані у project.yaml у розділах database і endpoints (розділи у цьому файлі названі англійською — так їх читає програма перевірки, перекладати їхні назви не можна).

Три слова, які часто трапляються далі на цій сторінці.

API

Читається «ей-пі-ай», від application programming interface. Це та частина твого сервісу, до якої звертається не людина очима, а програма: сторінка в браузері. Адреси, що починаються з /api/, віддають не оформлену сторінку, а самі дані. Звідси й ім’я твоєї служби — club-api.

Адреса API (у project.yaml — розділ endpoints)

Одна конкретна адреса разом зі словом, яке каже, що з нею робити: GET /api/habits — віддай список, POST /api/habits — прийми новий запис, DELETE /api/habits/{id} — видали запис із таким номером. Слово перед адресою браузер надсилає разом із запитом, і сервіс за ним розрізняє, чого від нього хочуть.

JSON

Читається «джейсон». Формат, у якому дані записують текстом так, щоб їх легко читала програма: список у квадратних дужках, кожен запис у фігурних, поле й значення через двокрапку. Саме в ньому GET /api/habits віддає твій список.

ssh bohdan.g9@91.219.61.4
cd ~/app
git status --short
git log --oneline | head -5

git add -A
git commit -m "Останні правки перед релізом"

cd ~/app
/opt/club/venv/bin/python -m pytest -q tests

.....                                                 [100%]
5 passed in 0.71s

less ~/app/FEEDBACK.md

nano ~/app/PLANS.md

# Що зробити після курсу

- Нагадування о 20:00 (просив брат, потрібна робота з часом).
- Сторінка статистики за тиждень.
- Можливість редагувати назву запису, а не тільки видаляти й додавати.

/opt/club/venv/bin/python -m pytest -q tests
git add -A
git commit -m "Кнопку перейменовано на «Додати до списку» за зауваженням із FEEDBACK"

nano ~/app/CHANGELOG.md

# Що змінилося

Проєкт: Трекер звичок. Автор: Богдан.
Номер версії: перше число — реліз, друге — нові можливості,
третє — виправлення.

## 1.0 — 13 вересня 2026

Перша версія, показана на демо-дні.

- Додано сторінку зі списком звичок і формою додавання.
- Додано збереження звичок у базу SQLite замість текстового файлу:
  дані не зникають після перезапуску служби.
- Додано адресу GET /api/habits — список звичок у форматі JSON.
- Додано адресу POST /api/habits — додавання звички з форми.
- Додано адресу DELETE /api/habits/{id} — видалення звички.
- Додано вхід власника за паролем: дивитися список може будь-хто,
  додавати й видаляти — тільки я.
- Виправлено помилку 500 при порожній назві звички: тепер відповідь 422
  з поясненням, що поле обов’язкове.
- Виправлено видалення неіснуючої звички: замість помилки 500 приходить 404.
- Додано напис «Поки що жодної звички» замість порожньої сторінки.
- Додано підписи до полів форми, щоб було зрозуміло, що вводити.
- Зменшено вагу сторінки з 812 КБ до 176 КБ: картинки переведено у формат WebP.
- Додано щоденну копію бази й інструкцію RUNBOOK.md на випадок,
  коли сервіс не відповідає.

cd ~/app
git add CHANGELOG.md PLANS.md
git commit -m "CHANGELOG: перелік змін від першого заняття до релізу 1.0"
git log --oneline | head -3

git tag -a v1.0 -m "Реліз 1.0: перша версія, показана на демо-дні"

git tag -n
git show v1.0 --stat | head -20

v1.0            Реліз 1.0: перша версія, показана на демо-дні

git push origin master
git push origin v1.0

git -C ~/repo.git tag
git -C ~/repo.git log --oneline | head -3

cd ~/app
./deploy.sh
echo $?

ГОТОВО: /api/ping відповів 200

grep url ~/app/project.yaml

  url: "https://bohdan.g9.klub.example/"

MY=https://bohdan.g9.klub.example
curl -s -o /dev/null -w 'сторінка: %{http_code}\n' "$MY/"
curl -s -o /dev/null -w 'api/ping: %{http_code}\n' "$MY/api/ping"

crontab -l
ls -lt ~/backups | head -3

~/app/backup.sh
ls -lt ~/backups | head -3

nano ~/DEMO.md

# План виступу — 5 хвилин

## Проблема (1 хв)
Для кого: мій молодший брат, 11 років.
Що заважало: забуває, що вже зробив, і о десятій вечора з’ясовує,
що не зробив нічого.

## Рішення (1 хв)
Що робить сервіс: показує список справ на день, кожну можна
відмітити одним дотиком.
Чому саме так: телефон завжди під рукою, зошит — ні.

## Показ (2 хв) — рівно три дії
1. Відкрити сторінку, показати список із чотирьох записів.
2. Додати справу «Вивчити вірш» — вона з’являється зверху одразу.
3. Відмітити її — лічильник унизу змінюється з 2 на 3.

## Історія поломки (1 хв)
Що зламалося: після надсилання порожньої форми сторінка показувала
помилку 500.
Як дізнався: сусід на занятті 08 надіслав порожню назву, і сервіс
відповів помилкою 500.
Що зробив: додав перевірку, тепер приходить 422 і текст
«Назва не може бути порожньою».

## Якщо не відкриється
Запасна адреса: http://91.219.61.4/u/bohdan.g9/
Поки перезапускаю службу, розповідаю, як влаштована база.

journalctl --user -u club-api -f

nano ~/app/FEEDBACK.md
~/app/backup.sh
ls -lt ~/backups | head -2

Що перевіряє автоматика

П’ять критеріїв заняття 12. Чотири з них перевіряє програма, п’ятий — L12.5 — оцінює викладач під час показу. Перевірка запускається за розкладом, тому відмітка в кабінеті з’являється не в ту саму секунду, коли ти виконав команду. Публічну адресу програма бере з ~/app/project.yaml, розділ server, поле url.

Домашнє завдання

cd ~/app
# правка в коді
/opt/club/venv/bin/python -m pytest -q tests
nano CHANGELOG.md          # новий розділ ## 1.0.1 із датою
git add -A
git commit -m "Виправлено сортування списку: найновіші записи зверху"
git tag -a v1.0.1 -m "Виправлення після демо-дня"
git push origin master
git push origin v1.0.1
./deploy.sh

Якщо щось не працює

fatal: tag 'v1.0' already exists

Тег із таким іменем уже поставлений — можливо, ти виконав команду двічі. Подивись, на якому він коміті:

git show v1.0 --stat | head -12
git log --oneline | head -3

Якщо тег стоїть на правильному коміті (тому ж, що зверху в git log), нічого робити не треба — переходь до git push origin v1.0. Якщо тег стоїть на старому коміті, а після нього ти зробив ще кілька, видали й постав заново:

git tag -d v1.0
git tag -a v1.0 -m "Реліз 1.0: перша версія, показана на демо-дні"
git tag -n

-d (delete) прибирає тільки позначку, самі коміти лишаються на місці. Але це безпечно, поки тег не надіслано в ~/repo.git. Якщо він уже там, не видаляй його: постав наступний номер v1.0.1. Переставляти вже опублікований тег — спосіб отримати два різні стани коду з однією назвою.

Тег є в ~/app, а в кабінеті критерій не зарахований

Перевір, що бачить сам репозиторій:

git tag -n
git -C ~/repo.git tag

Перша команда друкує тег, друга мовчить — тег не надісланий. Надішли:

git push origin v1.0

Якщо git відповідає Everything up-to-date, а тега в git -C ~/repo.git tag усе одно немає, подивись, чи туди ти надсилаєш:

git remote -v

Вивід — два рядки: git окремо показує, звідки він забирає коміти (fetch) і куди надсилає (push). Між іменем і шляхом стоїть символ табуляції, тому пробіл там може виглядати ширшим:

origin	/home/bohdan.g9/repo.git (fetch)
origin	/home/bohdan.g9/repo.git (push)

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

./deploy.sh зупиняється на першому кроці

Найчастіше вивід виглядає так:

==> 1/4 забираємо коміти з ~/repo.git
fatal: Not possible to fast-forward, aborting.

Це означає, що в ~/repo.git є коміти, яких немає в ~/app, і навпаки: історії розійшлися. Скрипт свідомо не намагається їх поєднати сам. Подивись, чим відрізняються:

git fetch origin
git log --oneline HEAD..origin/master
git log --oneline origin/master..HEAD

git fetch забирає інформацію про чужі коміти, нічого не змінюючи в твоїх файлах. Далі два нових слова. HEAD — так git називає коміт, на якому ти зараз стоїш, тобто верхній у твоєму ~/app. origin/master — верхній коміт гілки master у репозиторії ~/repo.git, яким git його запам’ятав під час fetch. Запис A..B між ними читається так: покажи коміти, які є в B і яких немає в A.

Тому перша команда покаже коміти, які є тільки в репозиторії, друга — які є тільки в тебе. Якщо перший список порожній, просто надішли своє: git push origin master. Якщо в обох списках щось є — це та ситуація, яку сьогодні не розв’язують поспіхом перед показом, клич викладача.

Сервіс не відповідає, а до виступу лишилося кілька хвилин

Три команди по черзі, у цьому порядку:

systemctl --user status club-api
journalctl --user -u club-api -n 30
systemctl --user restart club-api

Перша каже, у якому стані служба. active (running) — працює, failed — служба зупинилася через помилку і не змогла запуститися знову. Друга друкує тридцять останніх рядків журналу: читай знизу вгору, останній рядок із Error або Traceback і є причиною. Третя перезапускає службу.

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

grep ExecStart ~/.config/systemd/user/club-api.service

ExecStart=/opt/club/venv/bin/uvicorn main:app --host 127.0.0.1 --port 9536

У твоєму файлі число після --port буде інше — воно твоє на весь курс (заняття 02). Підстав його в команду нижче замість 9536:

curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:9536/api/ping

127.0.0.1 — це адреса «ця сама машина»: запит нікуди не виходить у мережу й не проходить через nginx. Якщо тут 200, а ззовні сторінка не відкривається, справа не в твоєму коді — скажи викладачеві.

Якщо служба зупиняється одразу після запуску, поверни код до стану релізу:

cd ~/app
git stash
git checkout v1.0
systemctl --user restart club-api

git stash прибирає незбережені зміни вбік, щоб вони не заважали; git checkout v1.0 перемикає файли на той стан, який ти позначив тегом.

Після демо повернешся на гілку командою git checkout master — і попередження зникне, — а відкладені зміни дістанеш через git stash pop.

Гість не може відкрити сторінку зі свого телефона

Спочатку з’ясуй, у скількох людей так. Якщо не відкривається в одного, а в решти працює, річ у його телефоні чи мережі. Дай другу адресу — ту, що з цифрами: http://91.219.61.4/u/bohdan.g9/. Вона веде на ту саму теку й ту саму службу, але в ній немає імені, яке треба перетворювати на число: якщо мережа його оператора ще не знає, який IP відповідає твоєму сабдомену, адреса з цифрами відкриється однаково.

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

Окремий випадок — гість бачить сторінку, але додати запис не може. Це нормально: додавання й видалення на занятті 07 закриті паролем, і роблять їх тільки з твого входу. Скажи це вголос, інакше гість вирішить, що сервіс зламався.

Під час показу в базі з’явилися випадкові записи

Спокійно допрацюй виступ до кінця — на пів хвилини це не вплине. Після демо подивись, що там:

ls -lt ~/backups | head -3
sqlite3 ~/data/app.db "SELECT id, title FROM habit ORDER BY id DESC LIMIT 10;"

sqlite3 — програма, яка відкриває файл бази й виконує запит, написаний після неї в лапках. Тут запит просить показати номер і назву десяти останніх записів таблиці habit: ORDER BY id DESC — від найбільшого номера до найменшого, LIMIT 10 — не більше десяти рядків. Підстав назву своєї таблиці й своїх полів із project.yaml.

Якщо зайвих записів кілька, видали їх через свою ж сторінку — це швидше й безпечніше за роботу з базою напряму. Якщо їх десятки, відновлюй базу з копії за інструкцією з RUNBOOK.md: саме для цього ти робив свіжу копію на кроці 10. Зверни увагу, що разом із випадковими зникнуть і справжні записи, додані під час показу.