Difference between revisions of "Repo.php"

Revision as of 15:11, 24 June 2013

repo.php — скрипт обновления/установки, созданный нами и применяемый в Mediawiki4Intranet.

Зачем нужен собственный скрипт?

Теоретически, вместо него можно было бы использовать просто подмодули Git’а (git submodules), но у них есть определённые минусы:

1. Когда модулей под сотню — они медленные, ибо:
   • Не умеют делать shallow клоны, всегда клонируют модули полностью.
   • Не поддерживают параллельное обновление.
2. Сабмодули не могут работать с типичным расположением кода MediaWiki (если не клонировать репозиторий ядра), ибо:
   • Нельзя создать репозиторий, корень которого был бы submodule’ем.
   • Внутрь одного модуля нельзя поместить другой, не трогая его репозиторий.
   • Следовательно, репозиторий сборки должен являться клоном core с расширениями, подключёнными сабмодулями в extensions/ExtensionName. Изменения ядра в таком случае будут перемешиваться с изменениями модулей.

   А это неудобно, так как хочется отделить репозиторий «сборки» от кода и дать возможность легко клонировать сборки, создавать свои сборки, дополненные какими-то расширениями и т. п.

   Разве что можно было уйти от стандартного MediaWikовского расположения кода и поместить core в отдельную подпапку.

3. Есть различные неудобства и недостатки функционала:
   • В .gitmodules нельзя указать желаемые ветки модулей (например, «хочу ParserFunctions REL1_20»). Опять-таки предполагается, что за версией модуля разработчик следит сам.
   • Переключать один и тот же модуль между разными репозиториями нужно руками — например, Wikimedia → наш_Github или наш_Github → ваш_форк.
   • git archive не работает с сабмодулями — если хочется распространять архив с кодом всей сборки, нужно писать отдельный скрипт.
   • Не поддерживаются различные способы доступа к одному репозиторию, например http на чтение для всех и ssh на запись для разработчиков.

   То есть, если хочется нормально push’ить с использованием ssh-ключа, то нужно заставлять всех клонировать всё исключительно по ssh.

   • В различных ситуациях встречаются различные глюки. Например, «You are on a branch yet to be born» после неудачной попытки добавить submodule.

Часть этих проблем можно решить с помощью хелперов или bash-скриптов, однако мы решили сразу написать цельный инструмент.

Возможности repo.php

• Установка «сборок» на основе их описаний в ini-файлах, содержащих адреса репозиториев и имена требуемых веток
• Поддержка shallow checkout, «быстрых» рабочих копий для установки (method=ro) и «медленных» для разработки (method=rw)
• Быстрое обновление установленного кода на основе файла индекса, содержащего хеши ревизий
• Полное обновление всех модулей (что-то вроде git submodule foreach 'git pull')
• Параллельное обновление с красивым одновременным выводом состояния на экран с помощью escape-последовательностей (естественно, UNIX only)
• Поддержка произвольного расположения вытаскиваемых рабочих копий (в том числе друг внутри друга)
• Создание архива с полным кодом сборки
• Автоматическое переключение между разными репозиториями одного модуля
• Возможность легкого добавления поддержки нужных систем контроля версий (которая, правда, пока что не пригодилась)

Системные требования

• PHP 5.3 или новее
• Нормальная система (не винда) — Linux, FreeBSD или что-то подобное. На винде тоже может работать, но, во-первых, медленно (ибо не поддерживается pcntl => невозможно запускать команды параллельно), а во-вторых, никто эту работу не тестировал и вполне вероятно, что отвалится что-то ещё.
• Расширение pcntl

Как работать с repo.php

Установка сборки

• Если хотим коммитить — прописываем публичный ssh-ключ для github’а
• Клонируем головной репозиторий (configs)
• В нём запускаем php repo.php install mediawiki4intranet rw. mediawiki4intranet — имя сборки, rw — тип установки (если хотите коммитить — то rw, если нет — ro)

Обновление сборки

• php repo.php update

Коммит модуля

• Вносим правки
• Коммитим и push’им их git’ом, как обычно
• Идём в configs
• php repo.php update
• Коммитим и push’им configs

Добавление модуля

• Создаём удалённый репозиторий (на стороне github’а или другого сервера), или убеждаемся в том, что он уже создан до нас
• По аналогии добавляем описание модуля в mediawiki4intranet.ini (ИМЯ_СБОРКИ.ini)
• php repo.php update
• Коммитим и push’им configs

Удаление модуля

• Удаляем модуль из mediawiki4intranet.ini (ИМЯ_СБОРКИ.ini)
• Коммитим и push’им configs

Troubleshooting

Если что-то пошло не так — можно указать параметр '-j 1': php repo.php -j 1 update. Команды будут запущены последовательно и вы увидите полный вывод git’а, на основании которого можно попытаться понять, что произошло.

TODO

• Задание дополнительных remotes для устанавливаемых репозиториев. Например, 'wikimedia' для наших форков расширений.
• Более гибкое задание readonly/readwrite — возможность клонирования части репозиториев как readonly, а части — как readwrite. Либо, возможность клонирования по https, а push’а по ssh. Возможно, через те же remotes.