1Реліз і день показу

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

До кінця заняття в тебе буде:

• README.md із сімома розділами, написаними твоїми словами;
• RELEASE.md: що входить у версію 1.0, які в неї є слабкі місця і як повернутися назад, якщо щось зламається;
• git-тег v1.0 на коміті, де всі тести зелені;
• програма audit.py — фінальний аудит: ти сам допишеш її, і вона за десять пунктів скаже, що вже готово (✔), а що ні (✘);
• команда /version, що показує, яка версія бота зараз працює;
• план виступу на дві-три хвилини і порядок «дня показу».

Якщо в тебе немає TelegramУсе, крім живого повідомлення, ти зробиш через try_bot.py. На виступі замість живого чату покажеш його (приклади є в кроці 13). Пункти, де потрібен живий бот, викладач оцінить окремо.

Поки ти пишеш бота, код змінюється щодня. Але щоб сказати комусь «ось готова штука», треба вирізати з цього потоку одну мить і домовитися: ось це — версія 1.0. Така мить називається релізом (випуском), а її позначка в Git — тегом. Тег — це наклейка на конкретному коміті: гілка рухається вперед із кожним новим комітом, а тег лишається на місці.

Навіщо це? Через тиждень ти виправиш щось і зламаєш. Тоді git checkout v1.0 покаже тобі код тієї версії, яку ти колись показував гостям і яка працювала. Після такого перегляду поверни робочу гілку: git switch main (Git скаже про «detached HEAD» — це лише означає, що ти дивишся на старий коміт, а не працюєш на гілці). А щоб справді позбутися поганих змін, є git revert: вона додає новий коміт, що їх скасовує. Це й називається відкат. Ще корисне правило: тег ставлять на коміті, де вже проходять тести, інакше «версія 1.0» — це версія з відомою поломкою.

До тега додають короткий файл RELEASE.md із трьома відповідями: що в цій версії (мовою користувача: «бот відповідає на /ask», а не «переписав функцію»), які в неї слабкі місця («без підключення до ШІ-шлюзу бот відповідає ввічливою відмовою») і як відкотитися. Написати про слабкі місця самому — нормально: так роблять усі дорослі проєкти, і так ти сам вирішуєш, що гість почує першим.

README — це перше, що бачить людина, відкривши репозиторій на GitHub. У неї є приблизно тридцять секунд. Якщо за цей час вона не зрозуміє, що це і чи їй це потрібно, — закриє вкладку. Тому README пишуть не для себе і не для викладача, а для незнайомої людини, яка про твій проєкт нічого не знає.

У шаблоні сім головних розділів, і кожен відповідає на одне питання:

Тут можна попросити ШІ допомогти: «ось мій bot.py, запропонуй, як пояснити команди людині, що бачить бота вперше». Але розділ «Чого я навчився» мусить звучати твоїм голосом: його прочитають гості, і саме з нього видно, що проєкт зробив ти. До того ж автоперевірка шукає в розділах твій текст і справжні команди з твого bot.py, а не загальні фрази.

Пароль у README — ніколиУ README пишуть, що треба вписати в .env, але не самі значення. Токен бота у файлі, який лежить на GitHub, — це як лишити ключ від квартири в дверях.

Чекліст — список справ, які треба перевірити перед важливою подією; так робить пілот перед зльотом. Перелік із десяти пунктів ми зробимо не на папері, а як програму — audit.py. Аудит — це перевірка за списком: програма проходить пункти й для кожного друкує ✔ (гаразд) або ✘ (є що виправити, і чому). Ось усі десять:

Три пункти (2, 5 і 8) ти допишеш сам: у кожному стоїть заготовка «ще не написано», яку треба замінити своєю перевіркою. Правило одне: функція повертає "" (порожній рядок), якщо все гаразд, або речення про те, що не так.

Головна вимога до аудиту — правдивість. Аудит, який завжди каже ✔, гірший за відсутній: він дає хибний спокій, і ти йдеш на показ з відкритим токеном, думаючи, що все гаразд. Тому автоперевірка нижче на сторінці не просто запускає твій audit.py: вона перевіряє ті самі речі власним способом і порівнює. Якщо твій аудит каже ✔, а насправді не гаразд (або навпаки) — зараховано не буде.

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

• Токен і паролі не повинні з’являтися на екрані. Не роби cat .env і не відкривай .env у редакторі. Перед виступом виконай clear, щоб прибрати зі стрічки термінала старі команди.
• Чужі дані. У базі є імена однокласників, що писали боту. Не показуй сирі таблиці — показуй числа (їх вистачить).
• Репозиторій на GitHub — приватний. Показуй його із свого акаунта; якщо хочеш зробити публічним, спершу переконайся, що audit.py каже ✔ у пунктах 4 і 5.
• Запасний варіант. Якщо Telegram чи ШІ підведуть — покажи try_bot.py. Заздалегідь зроби знімки екрана найголовніших відповідей.

Після показу — змінити токен бота. Відкрий у Telegram @BotFather, напиши /revoke, вибери свого бота: старий токен перестане працювати, а BotFather видасть новий. Новий впиши в ~/app/.env і перезапусти службу. Навіщо, якщо ніби ніхто нічого не помітив? Заміна токена займає хвилину, а витік — це небезпека для всіх, хто писав боту: чужа людина зможе писати від імені твого бота і читати, що йому надсилають. Тому токен міняють після показу завжди, а не лише коли здається, що він «мигнув».

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

Порядок демо (п’ять кроків, щоб нічого не забути): 1) /start: бот вітається; 2) своя команда або /ask; 3) скрипт за розкладом або ранковий звіт; 4) відмова чужому: чужий номер пише /run privit і отримує «Ця команда лише для власника бота» — це видовищна частина, бо показує, що захист справжній; 5) /version: бот називає свою версію.

Правило виступу: репетируй уголос із секундоміром. Тихо прочитати в голові — це не репетиція; уголос ти одразу почуєш, де заплутався.

Куди рости. Ідеї для наступних проєктів, що спираються на те, що ти вже вмієш: бот-нагадувач про домашні завдання й контрольні; бот класу (розклад, оголошення, голосування); бот-вікторина з таблицею рекордів; моніторинг: бот пише, якщо твій сайт перестав відкриватись; бот-помічник з базою знань про твоє хобі (фільми, гра, спорт). Вчитися далі зручно з офіційної документації Python і Telegram Bot API, з безкоштовних курсів (Prometheus, Coursera), ютуб-каналів про Python, шкільних і студентських олімпіад та змагань з програмування.

Як зберегти бота після курсу. Важливо: акаунти й сервер школи можуть бути вимкнені, і бот на них зупиниться. Тому вже зараз у тебе є все, щоб його перенести:

• Код — у приватному репозиторії на GitHub (команда git clone завантажить його на будь-яку машину);
• Список змінних — у .env.example; значення (токен) ти знаєш або можеш отримати новий в @BotFather;
• База — у бекапі ~/backups/app-….db; його можна завантажити на свій комп’ютер командою scp із заняття 08.

Куди переносити:

• власний комп’ютер — старий ноутбук чи невеликий настільний комп’ютер удома: безкоштовно. Бот працює через polling (він сам питає Telegram, чи є нове), тож публічна адреса не потрібна;
• VPS — оренда маленького віртуального сервера: від кількох доларів на місяць, потрібна банківська картка дорослого;
• хмарні сервіси з безкоштовним рівнем — вони є, але умови часто міняються й нерідко потребують 18 років, тож перевір правила разом із дорослими.

Що робити на новому місці, завжди однаково: поставити Python і потрібні бібліотеки, зробити git clone, створити .env із токеном, відновити базу з бекапу, зробити службу з Restart=always (як у club-bot.service), написати боту /start. Один токен — один працюючий бот: перш ніж вмикати нового, вимкни старого, інакше Telegram буде видавати помилку конфлікту.

Репетиція переїздуУ кроці 12 ти перевіриш, що проєкт збирається з нуля з репозиторію. Якщо там тести проходять — переїзд буде нудним, а це якраз найкраще.

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

Список критеріїв і що саме вони означають — у таблиці вище, «Що перевіряє автоматика». Тут — та сама перевірка, але прямо зараз, без очікування на найближчий прохід за розкладом.

1. Репетиція вголос. Двічі розкажи свій виступ із секундоміром: уклався в 2–3 хвилини? Один раз — комусь удома чи другу. Спитай: що було незрозуміло?
2. Перевірка README очима друга. Дай посилання на свій README другу (або запиши його на папір) і попроси «запустити» бота лише за інструкцією, нічого в тебе не питаючи. Де він застряг — там README недописаний: виправ.
3. Розділ «Що далі». Додай у README розділ ## Що далі з трьома ідеями, куди рости (теорія, розділ 6). Одна з них має бути з нового для тебе: нова команда, інший сервіс, інша мова.
4. Після показу. Виконай три рядки «Після показу» з VYSTUP.md: /revoke у @BotFather, новий токен у .env, перезапуск, /start. Запиши в VYSTUP.md, о котрій годині це зробив.
5. Збережи. git add -A, git commit -m "Заняття 13: домашня робота", git push origin main і git push github main.

34L13.1: README не проходить

• немає розділу «## Для кого» (чи іншого) — заголовок має бути рівно з двома символами # і пробілом: ## Для кого, без двокрапки на кінці;
• замало твого тексту — у розділі лишилися рядки з TODO, незмінені рядки шаблону або менш як 40 символів твого тексту. grep -n "TODO" ~/app/README.md покаже, де саме;
• мало різних слів — розділ складається з повторів одного слова; напиши речення своїми словами;
• названо справжніх команд 2, треба щонайменше 4 — пиши команди у зворотних лапках, як `/help`, і лише ті, що є в твоєму боті (/start, /help, /ask, /whoami, /version…);
• «Що вміє» менше трьох різних пунктів — кожен пункт з нового рядка, що починається з - (дефіс і пробіл), і складається щонайменше з двох слів.

35L13.2: тег v1.0

• тега v1.0 немає — git tag -a v1.0 -m "Реліз 1.0";
• на коміті v1.0 немає теки tests — тег поставлено раніше за заняття 12 (або тести не додано в git: git ls-files tests). Збережи тести комітом і перенеси тег: git tag -fa v1.0 -m "Реліз 1.0";
• тести не проходять — git stash (сховати зміни), git checkout v1.0, BOT_POLLING=0 /opt/club/venv/bin/python3 -m pytest -q, подивись помилку; поверни робочу гілку: git switch main, git stash pop. Виправ на головній гілці, збережи комітом і перенеси тег;
• тег v1.0 не відправлено — git push origin v1.0 (після перенесення тега: git push -f origin v1.0, -f лише для тега, не для гілки);
• тег стоїть не на цій гілці — тег поставлено на коміті з іншої гілки (наприклад, на тій, де ти щось пробував). Перенеси тег на поточний коміт: git tag -fa v1.0 -m "Реліз 1.0".

36L13.3: RELEASE.md

• на початку RELEASE.md немає версії v1.0 — перший рядок має бути # Реліз v1.0;
• менше 3 різних пунктів (чи 2 у «Відомі обмеження») — пункти рядками, що починаються з - , не коротші за 12 символів і з двох слів і більше, без TODO; однакові пункти рахуються за один;
• немає команди git revert або git reset — у розділі «Як відкотитися» вона є в шаблоні, не видаляй;
• немає твого речення про перевірку відкату — допиши в «Як відкотитися» своє речення, як ти переконаєшся, що відкат вдався;
• лишились рядки заготовки TODO — grep -n "TODO" ~/app/RELEASE.md.

37L13.4: audit.py

• лишилась заготовка «ще не написано» — у функціях пунктів 2, 5 і 8 прибери рядок return "ще не написано (ЗАПОВНИ)" і напиши перевірку;
• має надрукувати рівно 10 рядків — не видаляй і не додавай перевірок у списку, їх має бути десять: у кожної є @check(...) над def;
• audit.py поставив ✔ біля пункту N, а насправді не гаразд: … — після двокрапки названо причину, яку побачила автоперевірка. Твоя перевірка занадто поблажлива: додай до неї саме цю умову. Навпаки (✘, хоча все гаразд) — вона занадто сувора чи хибна;
• розв’язок пункту 2 (спробуй спершу сам):

      f = APP / "RELEASE.md"
      if not f.exists():
          return "немає RELEASE.md"
      text = f.read_text(encoding="utf-8")
      if "TODO" in text:
          return "у RELEASE.md лишились рядки заготовки TODO"
      for title, need in (("Що в релізі", 3), ("Відомі обмеження", 2)):
          body = section(text, title)
          if body is None:
              return f"немає розділу «## {title}»"
          points = [l for l in own_text(body).splitlines() if l.startswith("- ") and len(l) > 12]
          if len(points) < need:
              return f"у «{title}» менше {need} пунктів"
      body = section(text, "Як відкотитися")
      if body is None:
          return "немає розділу «## Як відкотитися»"
      return "" if re.search(r"git (revert|reset)", body) else "у «Як відкотитися» немає git revert чи git reset"

• розв’язок пункту 5 (спробуй спершу сам):

      f = APP / ".env.example"
      if not f.exists():
          return "немає .env.example"
      if not run("git", "ls-files", ".env.example")[1]:
          return ".env.example не додано в git"
      names = {}
      for line in f.read_text(encoding="utf-8").splitlines():
          if "=" in line and not line.startswith("#"):
              k, v = line.split("=", 1)
              names[k.strip()] = v.strip()
      for line in (APP / ".env").read_text(encoding="utf-8").splitlines():
          if "=" in line and not line.startswith("#"):
              k = line.split("=", 1)[0].strip()
              if k not in names:
                  return f"у .env.example бракує {k}"
      return "" if all(len(v) <= 30 for v in names.values()) else "у .env.example схоже на справжнє значення"

38L13.5: секрети в репозиторії

• .gitignore не приховує .env — додай рядок .env у ~/app/.gitignore; а якщо .env уже відстежується: git rm --cached .env, збережи комітом;
• немає .env.example — крок 5, не забудь git add .env.example;
• значення секрету з .env є в історії git (коміт …) — токен (чи інший секрет) колись потрапив у коміт, і з історії він сам не зникне. Заміни токен: @BotFather → /revoke, новий — у .env, перезапуск служби. Історію чистить викладач: самому цей пункт не виправити;
• щось схоже на токен бота — у файлі, який потрапив у git (README, тест, bot.py), чи в старому коміті є рядок виду 123456789:AAH…. Прибери його, збережи комітом, а токен вважай скомпрометованим — як у попередньому пункті.
• Немає Telegram і немає справжнього токена в .env? Це не помилка: перевірка тоді шукає лише рядки, схожі на токен, і дивиться на .gitignore та .env.example.

39L13.6: бекап і відновлення

• таймер club-backup.timer не ввімкнено — systemctl --user enable --now club-backup.timer;
• найсвіжішій копії N год — таймер не працює або ввімкнули нещодавно: python3 backup.py зробить копію зараз;
• у копії таблиця порожня — у базі немає жодного запису: напиши боту /start або python3 try_bot.py "/start", потім знову python3 backup.py;
• немає ~/restore-test/app.db — python3 restore.py.

40L13.7: служба і таймер

• у club-bot.service немає рядка Restart=always — відкрий nano ~/.config/systemd/user/club-bot.service, у розділі [Service] додай Restart=always; тоді systemctl --user daemon-reload і systemctl --user restart club-bot;
• таймер ранкового звіту не ввімкнено — systemctl --user enable --now club-morning.timer;
• немає club-morning.timer — файли з заняття 09 не скопійовано: cp /opt/club/kurs/09/club-morning.* ~/.config/systemd/user/, daemon-reload, enable --now.