Неверный ход: архив принят за проект
Сдача выглядит убедительно. Исполнитель выгружает папку с исходниками, заказчик открывает её и видит знакомую картину: файлы на месте, структура читаемая, имена говорящие, объём внушительный. Проверяют наличие — код есть. Акт подписывают. Ошибка сделана именно здесь, и в этот момент она незаметна, потому что проверялось не то: наличие файлов вместо возможности собрать из них систему.
Сразу оговорка о слове, иначе инженерный читатель прочтёт его во втором значении. Сборкой здесь называется превращение исходного кода в то, что запускается, — исполняемый файл, образ прошивки, развёрнутый сервер. К монтажу платы, шкафа или изделия это слово в статье отношения не имеет, хотя в разговоре звучит одинаково.
Что такое среда сборки проекта
Между текстом программы и работающей системой стоит цепочка преобразований, и у каждого звена есть свои условия. Средой сборки называют весь набор этих условий: чем собирать, из чего собирать, в каком порядке и куда потом ставить. Часть набора хранится в проекте файлами, а часть — состоянием чужого компьютера, и именно вторая часть теряется молча.
- •Инструменты с точными версиями: компилятор, сборщик, интерпретатор — не «последняя версия», а та, на которой проект собирался и проверялся,
- •Зависимости с зафиксированными версиями и указанием, откуда они берутся,
- •Сборочные скрипты и параметры запуска: что вызывается, в каком порядке, с какими ключами,
- •Шаблоны конфигурации с пустыми полями и перечень секретов, которые в эти поля подставляются,
- •Порядок развёртывания: куда система ставится, что должно быть на сервере до неё, чем проверяется запуск,
- •Для устройств — среда прошивания: программатор и схема подключения, порядок записи, карта областей памяти, которые нельзя затирать,
- •Ключ, которым подписываются обновления, если устройство проверяет подпись,
- •Инструкция, написанная для человека, который этот проект не писал.
Что уезжает в архиве, а что остаётся на машине разработчика
| Что нужно для сборки | Где это живёт на самом деле | Есть ли в архиве исходников |
|---|---|---|
| Текст программы | в репозитории проекта | да — это и есть срез файлов |
| Версии компилятора и инструментов | установлены на машине исполнителя | нет: установка не является файлом проекта |
| Зависимости и их версии | подтягиваются при сборке из внешних хранилищ | список — если он есть; точные версии попадают в него, только когда их зафиксировали отдельным действием |
| Переменные окружения и пути | в настройках оболочки и среды разработки | нет |
| Ключи, токены, сертификаты | в личном хранилище исполнителя | нет — и класть их туда не следует |
| Порядок развёртывания | в памяти того, кто разворачивал последний раз | нет |
| Настройки программатора и порядок прошивания | в проекте прошивальщика на его компьютере | нет |
Строки таблицы объединяет одно свойство. Всё, чего в архиве нет, файлом проекта никогда и не было — это настроенное состояние чужого рабочего места. Поэтому пропуск не выглядит пропуском: из переданной папки ничего не пропало, там просто с самого начала не было второй части комплекта.
Почему в день приёмки ошибка не видна
Принимают работу по работающей системе. Показывают сайт, который открывается, устройство, которое включается и отвечает по шине, сервер, на котором всё крутится. Всё перечисленное — результат уже выполненной сборки, а не доказательство того, что её можно повторить. Между «оно работает» и «его можно собрать заново» разница ровно в один вопрос, и на демонстрации этот вопрос не возникает: собирали в последний раз не вы и не на вашей машине.
Второй слой ещё неприятнее: незаписанное не видно и самому исполнителю. Настройка, сделанная однажды и с тех пор работающая, следа в проекте не оставляет — она перестаёт напоминать о себе ровно потому, что сработала, и в перечень попасть ей неоткуда. Поэтому просьба «отдайте среду сборки» получает честный ответ: он отдаёт то, что считает средой. Недостающее выясняется не разговором, а действием.
Чем это кончается
Последствия зависят не от размера проекта, а от того, сколько знания жило вне файлов. Ниже — во что превращается правка на одну строку, когда среды нет.
| Что за проект | Что ломается без среды | Во что превращается мелкая правка |
|---|---|---|
| Сайт на распространённой системе управления | сборка как таковая не нужна, но часть настроек живёт в базе и в админке, а не в файлах | разбор рабочего сервера и восстановление по частям |
| Своя серверная система | проект не поднимается на новой машине | подбор окружения перебором версий, пока не запустится |
| Прошивка устройства | исходники есть, а образ из них собрать нечем | подбор версий инструментов, пока поведение не совпадёт с работающим |
| Устройство с проверкой подписи обновлений | без закрытого ключа новый образ не подписать, а неподписанный загрузчик отвергает | обновление по сети прекращается; остаётся то, что делается с устройством в руках, — и то не в любой конструкции |
Как отличить среду от среза: проверка одним действием
Проверка одна, и она делается действием, а не сверкой списка. Проект собирают и разворачивают на машине, где его никогда не собирали, силами человека, который его не писал, по написанной инструкции. Всё, что придётся спросить у автора по ходу, — это и есть недостающая часть среды; её дописывают в инструкцию тут же, а не запоминают.
- •Взять чистую машину — ту, где проект ни разу не собирался и где нет ничего от прежней работы,
- •Поставить только то, что названо в инструкции, и ровно тех версий, что там названы,
- •Собрать и развернуть по инструкции, отмечая каждое место, где пришлось догадываться или звонить,
- •Для устройства — прошить собранный образ в отдельный экземпляр и сравнить его поведение с эталонным,
- •Сверить собранное с тем, что работает в бою: поведение, версию на странице, ответ сервиса, а где сборка повторяется побайтово — и контрольную сумму образа.
Действие одно, но одноразовым оно не бывает, потому что среда меняется вместе с проектом: обновилась библиотека, добавился шаг развёртывания, сменился программатор — и инструкция, верная на прошлом этапе, описывает уже не тот проект. Отсюда режим: проверку ставят в конец каждого этапа работ, и тогда расхождение вылезает по одному пункту за раз, а не всё сразу в день сдачи.
Это же действие есть чем закрепить: в договоре оно стоит критерием приёмки, рядом с событием перехода прав и порядком отзыва доступов, — так оно разобрано в статье что проверить в договоре до ухода подрядчика. Здесь то же действие взято со стороны состава: список того, что пришлось спросить у автора по ходу сборки, и есть перечень недостающего в среде — и превращается он не в претензию, а в дописанные строки инструкции.
Тот же разрыв в других местах передачи
Разрыв между «файлы отданы» и «этим можно пользоваться» повторяется везде, где результат работы передают выгрузкой. С данными с объекта происходит то же самое: файл открывается посторонней программой, а внутри — колонка значений без единиц измерения и без привязки к точкам, так что формально выгрузка получена, а работать с ней нечем. Что просить заранее, чтобы это не повторилось, разобрано в статье как выгрузить свои данные из диспетчеризации.
Если среда потеряна не в теории, а уже, и речь о железе, работа начинается не с исходников, а с чтения памяти живого устройства и разбора бинарника — порядок и границы такой работы описаны в статье как восстанавливают прошивку без исходников. Обходится это дороже, чем описать среду в тот период, когда её ещё есть кому описывать.
Что передаём мы и почему именно так
Передача среды сборки у нас не отдельная услуга и не жест доброй воли: она названа в описи того, что остаётся у заказчика, — рядом с правами на результат и документацией, и формулировка там ровно та же, что вынесена в заголовок этой статьи. Для электроники и прошивок набор такой: права на результат, исходники, среда сборки и конструкторская документация — с расчётом на то, что другой инженер продолжит работу без нас. Полный перечень того, что остаётся у вас, — на странице что мы делаем и что остаётся у вас.
И встречная оговорка, без которой это было бы обещанием на словах: инструкция, которую никто не проверял, стоит немногим больше архива, а проверить её своими руками автор не может — он знает недописанное наизусть. Поэтому просить у нас сборку на чистой машине разумно, и просить её стоит в середине работ, а не в день расставания: найденное тогда ещё дописывается в инструкцию.
Частые вопросы
Чем среда сборки отличается от исходного кода?
Исходный код — это текст программы. Среда сборки — условия, при которых из этого текста получается то, что запускается: версии инструментов, зависимости, сборочные скрипты, порядок развёртывания. Код без среды читается, но в работающую систему не превращается, а среда без кода бесполезна. В передаче это две отдельные строки, и наличие одной ничего не говорит о второй.
Подрядчик прислал архив с кодом — как понять, есть ли там среда сборки?
Не по составу папки, а действием: попросить собрать и развернуть проект с нуля на машине, где его никогда не собирали, по письменной инструкции и без подсказок автора. Всё, что по ходу придётся уточнять голосом, и есть недостающая часть среды — её дописывают в инструкцию сразу. Проводить такую проверку имеет смысл, пока договор действует и исполнителю есть зачем отвечать.
Можно ли восстановить среду сборки, если исполнитель уже недоступен?
Смотря что потеряно. Версии инструментов и зависимости восстановимы в принципе: их подбирают по косвенным признакам и по тому, что проект требует при сборке, а результат сверяют с работающей версией — это отдельная работа с отдельной ценой, дороже и дольше, чем получить описание от автора, пока он на связи. Закрытый ключ подписи не восстанавливается вовсе: подобрать его нельзя, и здесь помогает не разбор проекта, а только конструкция самого устройства — допускает ли она замену доверенного ключа.
Пароли и ключи тоже входят в передаваемую среду сборки?
Сами значения — нет. Передают шаблоны конфигурации с пустыми полями и перечень того, что в них подставляется: какой ключ, для какого сервиса, где он выпускается и кем. Боевые ключи в архив не кладут — иначе к риску потерять проект добавляется утечка доступов. Ключ подписи прошивок стоит особняком: его разумно выпускать на стороне заказчика с самого начала, а не передавать в конце.
Что такое воспроизводимая сборка?
В строгом смысле — свойство проекта, при котором одна и та же версия исходников, собранная в описанном окружении, даёт побайтово совпадающий результат. Добиться полного совпадения удаётся не всегда, и для приёмки достаточно более слабого условия: проект собирается у постороннего человека и ведёт себя так же, как работающая версия. Именно это условие делает передачу проверяемой, а не декларируемой.