Release bundle: бінарник, README, examples та notes

1. Навіщо потрібен release bundle

Якщо ви лише починаєте, дуже легко потрапити в пастку: здається, що мета розробки — отримати файл, який запускається. І це правда… приблизно перші пів години. А потім реальність починає ставити запитання, і всі вони звучать як варіації на тему: «А що це за штука і як нею користуватися?». Користувач (або ви за тиждень) не зобов’язаний пам’ятати, які в програмі є прапорці, які команди підтримуються, де подивитися версію і що робити, якщо «воно не запускається у Windows».

Release bundle — це спроба бути ввічливим інженером. Ми не просто віддаємо «ось вам бінарник, щасти», а передаємо невеликий набір артефактів, що відповідає на базові запитання: що це, як запустити, як перевірити версію, де подивитися приклади, що змінилося. Це схоже на ситуацію, коли ви даруєте людині кавомолку: можна, звісно, вручити лише мотор і дроти, але інструкція та пара рецептів помітно підвищують шанс, що ви залишитеся друзями.

Release bundle як контракт поширення

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

Важливо, що цей контракт працює і для вас самих. За місяць ви розбиратимете баг-репорт на кшталт «у вас нічого не працює», і раптом виявиться, що найкорисніше запитання — «А покажіть вивід todo --version». Якщо версія всередині бінарника не вшита і не виводиться, ви починаєте грати в інженерну рулетку: «здається, це був реліз… чи не реліз… чи це я збирав минулого тижня…».

Мінімальний склад release bundle

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

Зручно мислити так: є «серце» — бінарник — і «обв’язка», яка робить це серце придатним до життя поза вашим ноутбуком.

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

todo_1.3.0_linux_amd64

todo_1.3.0_windows_amd64.exe

README.md

README.txt

examples/

RELEASE_NOTES.md

CHANGELOG.md

Зверніть увагу: це не список «щоб було гарно», а мінімальний набір, який перетворює запуск на передбачувану дію. І так, якщо вам здається, що все й так зрозуміло, то вітаю — ви ще не дійшли до того моменту, коли документація здається зайвою. Майбутній ви це оцінить.

2. Як виглядає bundle для проєкту todo

Від цього моменту говоритимемо так, ніби в нас є навчальний CLI-застосунок todo — ми розвиваємо його впродовж усього курсу: він уміє створювати задачі, показувати список, позначати їх виконаними, зберігати дані й друкувати все це в stdout. Ми не розширюватимемо функціональність зараз; ми будемо упаковувати вже готове.

Уявімо, що ми підготували реліз версії 1.3.0 для Linux amd64. Тоді release bundle можна уявити як директорію:

todo_1.3.0_linux_amd64/
    todo
    README.md
    RELEASE_NOTES.md
    examples/
        quickstart.txt
        demo-session.txt

А для Windows:

todo_1.3.0_windows_amd64/
    todo.exe
    README.md
    RELEASE_NOTES.md
    examples/
        quickstart.txt
        demo-session.txt

Навіть без архівів і «справжнього релізного процесу» вже видно головне: користувач відкрив папку й одразу зрозумів, куди дивитися.

5. Іменування артефактів

Коли ви робите один бінарник «для себе», можна назвати його хоч a.out, хоч final_final2_really. Але щойно з’являється більше одного артефакту, починається плутанина: який із них для macOS, який — для Linux, який — новий, який — старий, чому один не запускається (спойлер: тому що ви намагаєтеся запустити бінарник для іншої архітектури).

Тому в релізах ми прагнемо до нудної, але інформативної схеми іменування:

• назва застосунку (todo)
• версія (1.3.0)
• цільова ОС (linux, windows, darwin)
• архітектура (amd64, arm64)
• розширення .exe для Windows

Це можна зібрати рядком у Go, і корисно тримати логіку в одному місці, щоб потім не шукати в проєкті 12 різних форматів.

Невеликий приклад — ми не ускладнюємо, а просто показуємо ідею; це може жити в internal/buildinfo або поруч:

package buildinfo

import (
	"fmt"
	"runtime"
)

func ArtifactName(app, version string) string {
	return fmt.Sprintf("%s_%s_%s_%s", app, version, runtime.GOOS, runtime.GOARCH)
}

Якщо викликати це й роздрукувати результат, вийде щось на кшталт:

package main

import (
	"fmt"

	"example.com/todo/internal/buildinfo"
)

func main() {
	fmt.Println(buildinfo.ArtifactName("todo", "1.3.0")) // todo_1.3.0_linux_amd64
}

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

6. README: що в ньому важливо

README багато хто пише за принципом «аби був». У результаті з’являється файл, де написано: «Це застосунок todo. Він робить todo.» Дякую, звісно, але це як інструкція до мікрохвильовки: «Підігріває їжу».

Хороший README для CLI — це коротка дорожня карта. У нього є одна головна мета: щоб людина, яка бачить проєкт уперше, за 2–3 хвилини змогла:

• запустити бінарник,
• побачити довідку,
• виконати один типовий сценарій,
• зрозуміти, де дивитися версію,
• зрозуміти, куди звертатися, якщо все зламалося, або хоча б що додати до повідомлення.

У README майже завжди корисні такі блоки:

1. Що це таке (2–3 речення, без роману).
2. Швидкий старт: 3–6 команд, які можна копіювати.
3. Довідка: як побачити --help і --version.
4. Де лежать приклади: посилання на папку examples/.
5. Обмеження, якщо вони є: наприклад, «файл даних зберігається там-то».

Щоб це було наочніше, ось «скелет» README — як текст, а не як догма. Зверніть увагу: це не «список вимог», а мінімальний сценарій спілкування з людиною.

# todo

Невеликий CLI-трекер задач: додавати задачі, показувати список, позначати їх виконаними.

## Швидкий старт

1) Подивіться версію:
   todo --version

2) Подивіться довідку:
   todo --help

3) Додайте задачу:
   todo add "купити молоко"

4) Покажіть список:
   todo list

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

7. examples/: приклади використання

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

У нашому todo зручний приклад — це «демо-сесія»: набір команд і очікуваний вивід, хоч би частково. Навіть якщо користувач не читатиме весь файл, він побачить шаблон: які команди бувають і що вони друкують.

Приклад файла examples/quickstart.txt може виглядати як звичайний текст. Зауважте: це не код на Go, тому тут ми нічого не компілюємо — лише показуємо, як користуватися.

# Швидкий старт: todo

todo --version
todo --help

todo add "прочитати лекцію про release bundle"
todo list
todo done 1
todo list

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

8. Release notes: RELEASE_NOTES.md

«Release notes» звучать солідно, ніби у вас компанія на тисячу людей і окремий відділ маркетингу. На практиці це просто чесна відповідь на запитання: «Що змінилося?». У світі Go це звична практика: релізи супроводжуються нотатками, і навіть в оголошеннях про релізи Go регулярно звучить «прочитайте release notes».

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

Ось приклад того, як може виглядати RELEASE_NOTES.md:

# Нотатки до релізу

## 1.3.0

Додано:
- прапорець --version (показує версію, коміт і дату збірки)

Виправлено:
- акуратніші повідомлення про помилки через неправильний id задачі

Змінено:
- вивід списку задач став стабільнішим (сортування)

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

9. Що має вміти бінарник у складі bundle

Цей розділ важливий, бо він пов’язує файли в наборі та поведінку програми. З погляду користувача, release bundle — це не лише README. Це ще й упевненість, що сам бінарник не поводиться як примхливий кіт: сьогодні запускається, завтра — не хоче.

Тому в CLI майже завжди мають бути дві діагностичні гілки, незалежні від решти логіки:

1. --help (або help як команда) — показує usage.
2. --version — показує версію.

Ми вже реалізували --version. Залишилося переконатися, що --help теж дружній, і що help/usage не приховує важливої інформації.

Ось маленький приклад, як можна прив’язати flag.Usage до «About» із buildinfo. Це не «єдино правильний» варіант, але він добре показує ідею: help — частина контракту.

package main

import (
	"flag"
	"fmt"
	"os"

	"example.com/todo/internal/buildinfo"
)

func main() {
	flag.Usage = func() {
		fmt.Fprintln(os.Stderr, buildinfo.About())
		fmt.Fprintln(os.Stderr, "Usage: todo [flags] <cmd> [args]")
		flag.PrintDefaults()
	}
	flag.Parse()
}

Користувач вводить todo --help і бачить не бездушне «Usage», а ще й ідентичність продукту. І якщо він потім надсилає вам скриншот, у вас уже є версія й коміт прямо в цьому тексті.

Проста модель release bundle в голові інженера

Тут корисно зафіксувати модель, щоб не скочуватися назад у «я просто зібрав бінарник». Можна уявити процес як конвеєр, навіть якщо ви вручну виконуєте його трьома командами.

flowchart TD
    A[Вихідні коди + go.mod + залежності] --> B[go build]
    B --> C["Бінарник (цільові GOOS/GOARCH)"]
    C --> D[Перевірка: --version / --help]
    D --> E[Папка релізу: бінарник + README + examples + нотатки до релізу]

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

10. Типові помилки під час підготовки release bundle

Помилка №1: вважати, що реліз — це «викласти бінарник».
Зазвичай це закінчується тим, що користувачі пишуть «не працює», а ви починаєте витягувати з них інформацію по крихтах: яка ОС, яка версія, як запускали. Release bundle потрібен саме для того, щоб мінімальні відповіді були поруч: у README і в --version/--help.

Помилка №2: не розрізняти артефакти за платформами й архітектурами.
Коли поруч лежать todo для linux/amd64 і todo для darwin/arm64 з однаковим іменем, хтось обов’язково запустить «не те». І це буде та сама людина, яка потім скаже «ваш Go дивний». Лікується нудним, але правильним іменуванням: app_version_GOOS_GOARCH і .exe для Windows.

Помилка №3: робити README «про все на світі», але без quickstart, який можна скопіювати.
Парадоксально, але довгий опис гірший за короткий набір команд. Користувач хоче не філософію, а «дайте 3 команди, щоб побачити результат». Якщо quickstart відсутній, людина найчастіше закриває папку. Або відкриває вихідний код. А потім уже не закриває… бо лагодить ваш UX.

Помилка №4: ховати приклади в тексті, замість того щоб винести їх у examples/.
Коли приклади є лише всередині README, їх складніше підтримувати й важче посилатися на них у підтримці: «Відкрийте examples/demo-session.txt і виконайте команди». Папка examples/ створює відчуття, що проєктом користувалися не лише його автори.

Помилка №5: не мати release notes і потім не пам’ятати, що змінилося.
Це класика не лише для користувачів, а й для автора. Ви зробили «невелике виправлення», опублікували новий файл, а через два тижні не можете пояснити, чим 1.3.0 відрізняється від 1.2.9. Короткий RELEASE_NOTES.md дисциплінує і вас, і проєкт.