По документации Apple, Xcode 27.2 и последующие версии используют формат JSON по умолчанию для новых проектов; существующие проекты можно перевести на него отдельно (инструкция Apple по обновлению формата конфигурации). Это не причина немедленно менять все репозитории. На этой неделе выберите пилотный проект, проверьте его на изолированном CI-узле и заранее отрепетируйте откат. Если ваша производственная цепочка не подтверждена для нужных версий Xcode или вы не можете восстановить сборку после возврата формата, пока оставьте проект без изменений.
Эта статья для руководителей корпоративной iOS-платформы, которым нужно установить правила для нескольких репозиториев.
Она пригодится инженерам CI, проверяющим версии Xcode и поведение сборочных узлов.
Также она адресована ответственным за код-ревью и выпуск, которым важно ограничить риск слияний и отката.
Последняя проверка: 5 октября 2026 года. Формулировки о совместимости сверены с документацией Apple о формате проекта и примечаниями к выпуску Xcode.
Новые репозитории и действующие проекты требуют разных решений
Поддержка JSON в Xcode — это возможность выбрать формат проекта, а не требование преобразовать все уже работающие репозитории. Apple указывает, что Xcode 27 и последующие версии совместимы с форматом .xcproj, а начиная с Xcode 27.2 он принят как формат конфигурации по умолчанию для новых проектов. Возможность перевести существующий проект также описана Apple, но факт доступности операции не доказывает готовность конкретного CI и всех зависимых инструментов.
Для нового репозитория разумно начать с формата, который применяется по умолчанию в используемой командой версии Xcode, если обязательные проверки уже покрывают новый вариант. Для действующего проекта решение сложнее: нужно проверить генераторы, скрипты, локальные инструменты, поведение веток и процедуру выпуска. Не смешивайте эти два случая в корпоративной политике.
Можно ли перевести старый проект Xcode на JSON? Да, Apple описывает переход существующих проектов на .xcproj. Но перед изменением проверьте, что все используемые вами Xcode и инструменты работают с выбранным форматом, а результаты можно повторить в CI. Для производственной ветки переход должен быть отдельным изменением, которое можно отменить без одновременного отката несвязанных обновлений.
Для принятия решения используйте условия, а не общий приказ о миграции:
- Пилотируйте формат, если нужные версии Xcode подтверждены, проект собирается и тестируется на изолированном узле, а обратный путь проверен.
- Расширяйте переход по репозиториям, если пилот дал воспроизводимый результат, владельцы проектов сверили конфигурацию, а ревьюеры могут понять смысл различий.
- Оставьте текущий формат, если CI использует неподтверждённую версию Xcode, проект создают внешние инструменты с неизвестной совместимостью или восстановление после сбоя не проверено.
- Отложите изменение в производстве, если одновременно планируются обновление macOS, Xcode, генератора проекта или схемы подписи. Иначе при ошибке станет сложнее определить её источник.
Эти условия не заменяют внутренние требования безопасности и выпуска. Они задают минимальную техническую основу для решения о формате.
CI-платформа: «открывается локально» не значит «проходит выпуск»
Разделяйте два утверждения: установленная версия Xcode умеет работать с форматом проекта; ваша производственная цепочка стабильно выполняет на нём нужные задачи. Первое проверяется по официальным сведениям Apple о поддержке формата. Второе — только на вашей конфигурации: с используемыми схемами, настройками сборки, тестами, зависимостями и архивированием.
Документация Apple также связывает возможность пользоваться конкретной версией Xcode с системными требованиями. Поэтому прежде чем менять файл проекта, сопоставьте версию Xcode на CI-узле с установленной там macOS по таблице системных требований Xcode. Не делайте вывод о поддержке только по номеру версии, указанному в конфигурации очереди: зафиксируйте фактически запускаемый Xcode и состояние узла.
Можно ли собирать .xcproj на CI-узлах с разными версиями Xcode? Не считайте совместимость доказанной для произвольного набора версий. Apple указывает поддержку .xcproj в Xcode 27 и последующих версиях, однако для вашей комбинации узлов необходимо проверить применимые требования и выполнить сборку на каждой реально используемой версии. Если часть узлов работает на версии вне подтверждённой границы, удерживайте проект в прежнем формате или изолируйте такие узлы до отдельного решения.
Перед включением проекта в основную очередь проверьте всю цепочку. Команду xcodebuild и доступные параметры запуска сверяйте с справочником Apple по командной строке Xcode. Для конкретного репозитория фиксируйте как минимум:
- точный результат
xcodebuild -versionи выбранный путь к инструментам; - список проектов, схем и доступных целей сборки;
- разрешение зависимостей в условиях CI, а не только на рабочей станции;
- прохождение тех же сборок и тестов, которые обязательны для текущего выпуска;
- создание архива, если оно входит в штатный маршрут поставки приложения;
- журналы и параметры запуска, по которым другой инженер сможет повторить проверку.
Запись «сборка успешна» недостаточна для передачи результата. Сохраните ссылку на запуск CI, ревизию исходного кода, версию Xcode, выбранную схему и итог каждого обязательного задания. Так проверка останется воспроизводимой после того, как пилотная ветка будет закрыта.
Команда приложения: конфигурация проекта и внешние инструменты
Файл проекта — не единственный элемент, который может повлиять на результат. До переключения составьте для репозитория перечень targets, schemes, build settings и сценариев, которые изменяют или генерируют конфигурацию. Затем назначьте владельца для каждого элемента и укажите, как проверяется его корректность после преобразования.
Отдельно проверьте генераторы проектов, скрипты подготовки сборки и внутренние средства автоматизации, если они действительно используются вашей командой. Не предполагайте, что сторонний генератор, анализатор, редактор конфигурации или вспомогательный скрипт уже поддерживает новый формат. Для каждого фактически присутствующего в репозитории инструмента найдите подтверждение совместимости или проведите его собственный тест. Отсутствие сообщения об ошибке на рабочем компьютере не равно официальной поддержке.
Удобно завести таблицу испытаний в документации репозитория. Для каждой записи храните имя инструмента, его версию, действие с проектом, ожидаемый результат и ссылку на проверочный запуск. Если инструмент только читает файл, проверьте чтение; если записывает или пересоздаёт конфигурацию — проверьте и получившийся diff. Так команда не будет приписывать совместимость инструменту, который вообще не участвовал в пилоте.
Перепроверьте схемы и настройки сборки после перехода. Если в репозитории используются пользовательские схемы, сопоставьте их с тем, что видит команда xcodebuild, и проверьте настройки, важные для ваших вариантов сборки. Для самого управления схемами Apple публикует документацию по настройке схем проекта. Используйте её для понимания механики, но вывод о корректности конкретного приложения делайте по фактическим результатам CI.
Код-ревью: читаемость diff нужно оценивать на ваших изменениях
JSON может изменить то, как представлена конфигурация, но сама по себе смена представления не гарантирует более качественное ревью. Проверяйте, помогает ли новый diff ответить на вопрос «что изменилось и зачем» — особенно для изменения схемы, настройки сборки или состава целей. Сравнивайте однотипные изменения до и после переключения, а не рекламное описание формата.
Во время пилота попросите разработчика оформить обычное изменение проекта, которое уже встречается в вашем процессе. Ревьюер должен определить, какие настройки изменились, затронут ли продукт или только структура файла и не появились ли побочные изменения. Запишите, какие строки вызвали вопросы, что пришлось сравнивать вручную и совпало ли понимание автора и проверяющего.
Не ограничивайтесь одной веткой. Проведите изменение, в котором два участника затрагивают соседние части конфигурации, и проверьте разрешение конфликта с последующей сборкой. Это не доказывает, что формат всегда уменьшает конфликты; тест показывает, насколько предсказуем ваш рабочий процесс с ним. Если после разрешения конфликта команда не может уверенно объяснить итоговый diff, сначала улучшите правила ревью или редакторский процесс, а уже затем обсуждайте массовое переключение.
В результатах пилота храните сам diff, комментарии ревьюеров и сведения о повторной сборке. Такой набор фактов позволяет решить, принесло ли изменение пользу именно вашей команде, а не только изменило вид файла.
Администратор репозитория: возврат должен охватывать больше, чем файл
Apple описывает смену .pbxproj на .xcproj при обновлении формата проекта. Зафиксируйте состояние до и после перехода в отдельной ветке, чтобы было ясно, какие файлы добавлены, заменены или изменены. При этом успешное восстановление файла в Git ещё не подтверждает восстановление всей цепочки выпуска: могли измениться настройки CI, выбранная версия Xcode, генерируемые артефакты или связанные инструкции.
Для безопасной проверки выполните действия в таком порядке:
- Создайте отдельную ветку от состояния, которое сейчас собирается в производстве, и сохраните идентификатор исходной ревизии.
- Примените преобразование формата, не включая в тот же набор изменений обновления macOS, Xcode, зависимостей или настроек подписи.
- Просмотрите diff и сопоставьте перечень проектов и конфигураций с исходным состоянием.
- Запустите на изолированном CI-узле обязательные операции сборки, тестирования и архивирования для используемых схем.
- Верните ветку к исходному состоянию предусмотренным в вашем Git-процессе способом, затем повторите контрольную сборку и тест.
- Сохраните diff, журналы обоих запусков и вывод о том, какие действия потребуются для возврата связанных настроек CI.
Это не универсальная команда отката: способ зависит от ваших правил ветвления и защиты производственных веток. Важен проверяемый результат — исходная версия снова собирается по обычному маршруту, а не только то, что история Git позволяет отменить коммит. Как безопасно откатить переход формата в репозитории? Проверьте возврат в изолированной ветке и подтвердите сборку после него. Если CI-конфигурация менялась вместе с файлом, включите восстановление этих настроек в репетицию; один Git-откат файла не подтверждает, что публикационный процесс восстановлен.
Руководитель выпуска: пилот, расширение или временная пауза
Сведите выводы команд в один протокол: результат CI, версии инструментов, проверенные внешние зависимости, образцы ревью и итоги возврата. Для каждого репозитория итог должен быть одним из трёх: переход одобрен; переход возможен после указанных исправлений; переход отложен до появления подтверждённой конфигурации.
| Ситуация в репозитории | Решение по формату | Что должно быть подтверждено |
|---|---|---|
| Новый проект, создаваемый подходящей версией Xcode | Рассмотреть JSON как исходный формат | Требования к Xcode и macOS, сборка и тестирование в штатном CI |
| Действующий проект с проверенными узлами и инструментами | Провести отдельный пилот, затем расширять по репозиториям | Diff, рабочие схемы, результаты CI, ревью и возврат |
| Есть узлы или генераторы с неизвестной совместимостью | Оставить прежний формат или изолировать неопределённую часть | Подтверждение конкретных версий и повторяемый тест |
| Одновременно меняется несколько частей инструментария | Разнести изменения по независимым проверкам | Возможность определить причину сбоя и восстановить исходный выпуск |
Как понять, что форматная миграция не повредит текущему CI? Не по одному запуску на рабочей станции, а по сохранённым результатам в той же очереди и на тех же классах узлов, которые участвуют в выпуске. Сравните результаты до и после для обязательных задач и схем; подтвердите, что команда может провести возврат. Если остаётся неподтверждённая часть цепочки, решение должно быть «отложить» или «ограничить пилот», а не «раскатить везде».
Не объединяйте смену формата с обновлением Xcode или macOS. Если изменить несколько составляющих сразу, отрицательный результат не покажет, вызван ли он структурой .xcproj, версией инструментария или состоянием узла. Если в будущем появится необходимость пересмотреть совместимость, официальные сведения о формате и системных требованиях нужно проверять снова, а не переносить выводы старого пилота на новые версии.
Для пробного CI полезен отдельный Mac-узел, который не обслуживает производственный выпуск и на котором можно воспроизвести версию Xcode и операции вашего проекта. При оценке такого варианта заранее определите требования к доступу, сохранению результатов, удалению тестовых данных и возврату окружения. Сравните стоимость такого временного узла с использованием собственного оборудования по фактическим внутренним тарифам и загрузке; универсальную экономию без данных вашей команды рассчитать нельзя. Ознакомиться с вариантами удалённого Mac можно на странице VMSPIN, а перед планированием пилота — сверить условия на странице тарифов.
Если сейчас вы тестируете формат на общей локальной машине или меняете сразу производственный CI, у такого подхода есть реальные недостатки: труднее изолировать влияние теста, хуже воспроизводится состояние узла и выше риск смешать пилот с выпуском. Для короткого пилота отдельный удалённый Mac может дать команде доступ к самостоятельной среде без предварительной закупки каждой тестовой машины. Но если нагрузка постоянная и тяжёлая, или испытания требуют физического оборудования и интерфейсов, собственный выделенный Mac может быть разумнее. Сначала зафиксируйте версию Xcode и сценарии приёмки; когда вам нужна дополнительная изолированная среда для проверки проекта, рассмотрите аренду Mac у VMSPIN и подтвердите пригодность конкретного узла до производственного использования.