Repo.php
repo.php — скрипт обновления/установки, созданный нами и применяемый в Mediawiki4Intranet.
Contents
Возможности repo.php
- Установка «сборок» на основе их описаний в ini-файлах, содержащих адреса репозиториев и имена требуемых веток
- Поддержка shallow checkout, «быстрых» рабочих копий для установки (method=ro) и «медленных» для разработки (method=rw)
- Быстрое обновление установленного кода на основе файла индекса, содержащего хеши ревизий
- Полное обновление всех модулей (что-то вроде git submodule foreach 'git pull')
- Параллельное обновление с красивым одновременным выводом состояния на экран с помощью escape-последовательностей (естественно, UNIX only)
- Поддержка произвольного расположения вытаскиваемых рабочих копий (в том числе друг внутри друга)
- Создание архива с полным кодом сборки
- Автоматическое переключение между разными репозиториями одного модуля
- Возможность наследования сборок
- Возможность легкого добавления поддержки любых нужных систем контроля версий (которая, правда, пока что не пригодилась)
Системные требования
- PHP 5.3 или новее.
- Консольный Git-клиент, прописанный в пути.
- Нормальная система (не винда) — Linux, FreeBSD или что-то подобное. На винде тоже может работать, но, во-первых, медленно (ибо не поддерживается pcntl => невозможно запускать команды параллельно), а во-вторых, никто эту работу не тестировал и вполне вероятно, что отвалится что-то ещё. Возможно, будет нормально работать под Cygwin.
- Расширение 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
Создание своей сборки на основе нашей
- Клонируем наш репозиторий configs к себе — например, путём нажатия «Clone» на github. Либо — на любом другом сервере путём создания репозитория + клонирования нашего к себе на компьютер + push’а из локального репозитория в свой новый.
- Удостовериваемся, что команда git remote -v show выводит ваш новый репозиторий (а не наш configs).
- Создаём в новом configs собственный файл описания сборки — mediawiki4fuhrer.ini, и в нём пишем:
; включаем нашу сборку [_params] include = mediawiki4intranet ; можно добавить свой префикс для репозиториев ($REPO будет заменено на имя репозитория) prefix.mysrv = git:http://myserver.office.ru/git/$REPO ; добавляем или переопределяем часть расширений [extensions/MySuperExtension] repo = github:viewfuhrer/MySuperExtension branch = master ; и так далее...
- Скорее всего, вам потребуется версионировать и собственный вариант конфигурации (*Settings.php). Тут желательно тоже не трогать наш BaseSettings.php, а создать свой, включающий наш, и добавить его git add.
Далее внутри вашего нового configs запускаем команды:
php repo.php update mediawiki4fuhrer rw git add mediawiki4fuhrer.ini mediawiki4fuhrer-index.ini git commit -m 'Создал свою сборку' git push
После этого вы можете работать со своей сборкой так же, как и с нашей (обновляя/добавляя/удаляя расширения). Чтобы удалить расширение, просто переопредите его параметр repo пустотой ("repo=").
Создание архива / экспорт всех файлов в директорию
Следующая команда создаст копию сборки в директории <directory>, без системных директорий типа .git:
- php repo.php export <directory>
Для создания архива со сборкой — просто закатайте полученную директорию в архив.
Troubleshooting
Если что-то пошло не так — с недавних пор repo.php должен вывести полный текст всех ошибок. Если этого не произошло — можно указать параметр '-j 1': php repo.php -j 1 update. Команды будут запущены последовательно и вы увидите полный вывод всех вызываемых команд.
Зачем нужен собственный скрипт?
Теоретически, вместо repo.php можно было бы просто использовать подмодули Git’а (git submodules), но у них есть определённые минусы:
- Когда модулей под сотню — они медленные, ибо:
- Не умеют делать shallow клоны, всегда клонируют модули полностью.
- Не поддерживают параллельное обновление.
- Сабмодули не могут работать с типичным расположением кода MediaWiki (если не клонировать репозиторий ядра), ибо:
- Нельзя создать репозиторий, корень которого был бы submodule’ем.
- Внутрь одного модуля нельзя поместить другой, не трогая его репозиторий.
- Следовательно, репозиторий сборки должен являться клоном core с расширениями, подключёнными сабмодулями в extensions/ExtensionName. Изменения ядра в таком случае будут перемешиваться с изменениями модулей. Так, кстати, и делает Wikimedia Foundation в своей сборке.
- Но это неудобно, так как хочется отделить репозиторий «сборки» от кода и дать возможность легко клонировать сборки, создавать свои сборки, дополненные какими-то расширениями и т. п.
- Разве что можно было уйти от стандартного MediaWiki’овского расположения кода и поместить core в отдельную подпапку, а extensions — вне core.
- Есть различные неудобства и недостатки функционала:
- В .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-скриптов, однако мы решили сразу написать цельный инструмент.
TODO
- Задание дополнительных remotes для устанавливаемых репозиториев. Например, 'wikimedia' для наших форков расширений.
- Более гибкое задание readonly/readwrite — возможность клонирования части репозиториев как readonly, а части — как readwrite. Либо, возможность клонирования по https, а push’а по ssh.
Возможно, через те же remotes.Оказывается, git сам умеет fetch’ить с одного адреса, а push’ить на другой! - Провентилировать идею безиндексной работы с помощью сервиса, который бы кэшировал ревизии репозиториев.