Если настройка локальной среды разработки занимает больше 5 минут, или требует каких-то "врождённых" знаний, это налог на каждого разработчика. Я хочу просто клонировать репозиторий, запустить пару команд и получить работающую среду разработки...

Mark Allen

Думаю, что многие из вас за свою карьеру успели повидать много разных репозиториев. Среди них наверняка были хорошие и не очень; большие и маленькие; с Python, Go, Java, C++ и много чем ещё. Все они были очень разными, но первые вопросы скорее всего были одинаковыми:

• что тут вообще можно/нужно делать (запустить тесты, линтеры, билд, песочницу, что-то ещё),

• как это делать.

В хороших репозиториях можно рассчитывать на README и Docker. В плохих... ну вы сами знаете - скорее всего README нет, если есть, то не актуальный и написано там что-то вроде:

установите вот это и это, настройте вот то, спросите у Васи куда добавить вот это, удалите вот это, присядьте 6 раз, подождите неделю и может быть что-то запустится".

Но даже если вам повезло иметь дело только с хорошими проектами, переключаться между ними всё-равно может быть болезненно - README организованы по-разному, искать нужные команды нужно в разных местах, сами команды отличаются друг от друга, опций в них может быть миллион, алиасы на всё не посоздаёшь, запомнить столько всего разного тоже сложно.

Аналогия, которая всё расставит по своим местам

Давайте на минутку отвлечёмся на аналогию с реальной жизнью, например с автомобилем. От всех автомобилей вы ожидаете некого базового набора функций:

• попасть в автомобиль,

• добраться из точки А в точку Б,

• выйти из автомобиля,

Кажется просто? А теперь представим, что вам нужно часто пересаживаться с одного автомобиля на другой. Внезапно даже эти простые действия могут превратиться в проблему:

Попасть в автомобиль? Ну...

• в одних автомобилях доступ бесключевой, в других нет

• кнопки на ключах расположены по-разному

• видов автомобильных ручек можно насчитать минимум десяток.

• двери бывают сдвижные, распашные, бывают с открытием вверх, с электроприводом, или без.

Добраться из точки А в точку Б?

Проблем становится больше. Всё настолько сложно, что нужно этому несколько месяцев учиться и сдавать экзамены. Прежде чем куда-то поехать, нужно завести автомобиль:

• где-то нужно просто нажать кнопку старта,

• где-то требуется повернуть ключ (где-то нужно сначала нажать сцепление, где-то нет),

• где-то нужно ещё подтвердить, что ты не пьян,

• а бывали ещё и варианты с кик-стартером.

А когда мы всё-же трогаемся, начинаются настоящие проблемы:

• в одних автомобилях, чтобы ехать, вам нужно просто жать на газ

• в других надо научиться пользоваться педалью сцепления и рычагом МКПП;

• где-то рычаг МКПП слева, а где-то справа,

• где-то, чтобы включить заднюю скорость надо просто поставить рычаг в нужное положение, где-то предварительно надавить на него, где-то потянуть на себя какое-то колечко.

• с АКПП не легче - они могут быть под рулём, могут быть в виде шайбы, кнопок, или обычного рычага

Не так-то просто, согласитесь? Особенно если вы неопытный водитель, или впервые садитесь на автомобиль новой конструкции.

А теперь представьте альтернативу: производитель машины встроил в неё ассистента, который понимает обычный язык. Вы просто говорите:

• поехали домой,

• поехали в магазин,

• поехали по координатам <требуется добавить адрес>,

а всю остальную работу ассистент берет на себя: сам заводит машину, трогается, переключает передачи, включает поворотники и т.д. Так как интерфейс взаимодейставия с этим ассистентом - обычный человеческий язык (а на самом деле небольшая часть языка), то им могут пользоваться большинство людей старше 3-летнего возраста. Больше не нужно ждать 16 лет, проходить медкомиссию, учиться водить, сдавать экзамены, достаточно просто уметь произносить пару простых фраз на своём языке и ты можешь перемещаться на любом автомобиле, оборудованном таким ассистентом.

Вернемся к репозиториям - встречайте runo

runo это именно такой ассистент, но не для автомобилей, а для репозиториев. С ним вам больше не нужно будет искать в документации (если она есть :)) нужные команды, что-то настраивать, чтобы просто запустить тесты, или песочницу. Вам достаточно обратиться к ассистенту, он уже знает всё, что нужно об этом репозитории:

> ./runo
Following commands are available:
  * sandbox - runs server (API + UI) and DB locally
  * test - runs unit tests (pytest)
  * build - builds the project
  * pre-commit - quick checks/fixes of code formatting (ruff/mypy)
  * update-deps - updates dependencies
  * shell - debug container by running shell in interactive mode

Кажется, выглядит неплохо? Вы сразу знаете что тут положено делать и кажется теперь интуитивно понятно КАК нужно это делать - просто попросите ассистента:

> ./runo test

А заботу о деталях ассистент берет на себя. Он знает, что тесты нужно запускать в Docker контейнере, знает в каком, с какими параметрами, ну и в конце концов он знает, что это pytest:

> ./runo test
[+] Building 6.4s (13/13) FINISHED
 => [internal] load build definition from Dockerfile
...
======================================== test session starts ============================================
platform linux -- Python 3.13.7, pytest-8.3.5, pluggy-1.6.0

...
Required test coverage of 90% reached. Total coverage: 98.94%
======================================== 564 passed in 6.14s ============================================

В другом проекте/репозитории для запуска тестов может быть нужен совсем другой контейнер; там может быть не, Python, a Go, но об этих деталях вам не придётся беспокоиться. Если разработчики того репозитория тоже интегрировали runo, вы просто снова запускаете ./runo test:

> ./runo test
[+] Building 3.1s (7/7) FINISHED                                                                                                   docker:default
 => [internal] load build definition from Dockerfile                                                                                         0.0s
[+] Creating 2/2
 ✔ Network goapp-run-tests-674b3b2e-80bd-42be-8664-239414eda120_default       Created                                                    0.1s 
 ✔ Container goapp-run-tests-674b3b2e-80bd-42be-8664-239414eda120-postgres-1  Created                                                    0.5s 
[+] Running 1/1
 ✔ Container goapp-run-tests-674b3b2e-80bd-42be-8664-239414eda120-postgres-1  Started                                                    0.2s 
Waiting for postgres:5432 to become available...................
go test -p 1 -race -cover -coverprofile=coverage.out ./...
?       git.github.com/frwl/goapp          [no test files]
ok      git.github.com/frwl/goapp/server   4.385s  coverage: 69.7% of statements
ok      git.github.com/frwl/goapp/client   1.023s  coverage: 83.1% of statements
...
go tool cover -html=coverage.out -o coverage.html
[+] Running 2/2
 ✔ Container goapp-run-tests-674b3b2e-80bd-42be-8664-239414eda120-postgres-1  Removed                                                    0.9s 
 ✔ Network goapp-run-tests-674b3b2e-80bd-42be-8664-239414eda120_default       Removed                                                    0.2s  

Требуется мульти-платформенность? Не вопрос. Спросите у runo какие варианты разработчики данного репозитория решили поддерживать:

> ./runo --containers
Following containers are available:
  * Debian
  * Centos
  * RockyLinux

И вы можете выполнить нужную вам задачу для интересующей вас платформы:

> ./runo -c Debian build
Buld for Debian is running
...
done

А можете сразу для всех платформ:

> ./runo -c "*" test
Running test for Debian
PASSED
Running test for Centos
PASSED
Running test for RockyLinux
PASSED

И всё это без дополнительных зависимостей и установки чего бы то ни было. runo это 1 файл, который встраивается непосредственно в репозиторий и работает сразу из коробки для любых новых пользователей. Для работы ему требуется только наличие Python, начиная с версии 3.6 (кажется, что сегодня почти 100% систем отвечают этому критерию). Благодаря runo настройка локального окружения может стать тривиальной задачей (или вообще не потребоваться), вам не придется что-то устанавливать или конфигурировать. Вы сможете просто взять абсолютно новый ноутбук, клонировать на него репозиторий и он будет готов к работе. Как?

Вторая часть на подходе...

Во второй части мы интегрируем runo в репозиторий, рассмотрим детали, и разберём его конфиг. Вопросы, комментарии, предложения приветствуются.

Репозиторий runo: https://github.com/frwl404/runo