Difference between revisions of "Repo.php"

From Wiki4Intranet
Jump to: navigation, search
(Возможности repo.php)
(Создание своей сборки на основе нашей)
 
(15 intermediate revisions by the same user not shown)
Line 1: Line 1:
 
'''repo.php''' — скрипт обновления/установки, созданный нами и применяемый в [[Mediawiki4Intranet]].
 
'''repo.php''' — скрипт обновления/установки, созданный нами и применяемый в [[Mediawiki4Intranet]].
 +
 +
== Возможности repo.php ==
 +
 +
* Установка «сборок» на основе их описаний в ini-файлах, содержащих адреса репозиториев и имена требуемых веток
 +
* Поддержка shallow checkout, «быстрых» рабочих копий для установки (method=ro) и «медленных» для разработки (method=rw)
 +
* Быстрое обновление установленного кода на основе файла индекса, содержащего хеши ревизий
 +
* Полное обновление всех модулей (что-то вроде <tt>git submodule foreach 'git pull'</tt>)
 +
* Параллельное обновление с красивым одновременным выводом состояния на экран с помощью escape-последовательностей (естественно, UNIX only)
 +
* Поддержка произвольного расположения вытаскиваемых рабочих копий (в том числе друг внутри друга)
 +
* Создание архива с полным кодом сборки
 +
* Автоматическое переключение между разными репозиториями одного модуля
 +
* Возможность наследования сборок
 +
* Возможность легкого добавления поддержки любых нужных систем контроля версий (которая, правда, пока что не пригодилась)
 +
 +
== Системные требования ==
 +
 +
* PHP 5.3 или новее.
 +
* Консольный Git-клиент, прописанный в пути.
 +
* Нормальная система (не винда) — Linux, FreeBSD или что-то подобное. На винде тоже может работать, но, во-первых, медленно (ибо не поддерживается pcntl => невозможно запускать команды параллельно), а во-вторых, никто эту работу не тестировал и вполне вероятно, что отвалится что-то ещё. Возможно, будет нормально работать под Cygwin.
 +
* Расширение [http://www.php.net/manual/ru/book.pcntl.php pcntl].
 +
 +
== Как работать с repo.php ==
 +
 +
=== Установка сборки ===
 +
 +
* Если хотим коммитить — прописываем публичный ssh-ключ для github’а
 +
* Клонируем головной репозиторий ([https://github.com/mediawiki4intranet/configs configs])
 +
* В нём запускаем <tt>php repo.php install mediawiki4intranet rw</tt>. mediawiki4intranet — имя сборки, rw — тип установки (если хотите коммитить — то rw, если нет — ro)
 +
 +
=== Обновление сборки ===
 +
 +
* <tt>php repo.php update</tt>
 +
 +
=== Коммит модуля ===
 +
 +
* Вносим правки
 +
* Коммитим и push’им их git’ом, как обычно
 +
* Идём в configs
 +
* <tt>php repo.php update</tt>
 +
* Коммитим и push’им configs
 +
 +
=== Добавление модуля ===
 +
 +
* Создаём репозиторий для модуля на стороне github’а или другого сервера (или убеждаемся в том, что он уже создан до нас)
 +
* По аналогии добавляем описание модуля в mediawiki4intranet.ini (ИМЯ_СБОРКИ.ini)
 +
* <tt>php repo.php update</tt>
 +
* Коммитим и push’им configs
 +
 +
=== Удаление модуля ===
 +
 +
* Удаляем модуль из mediawiki4intranet.ini (ИМЯ_СБОРКИ.ini)
 +
* Коммитим и push’им configs
 +
 +
=== Создание своей сборки на основе нашей ===
 +
 +
* Клонируем наш репозиторий configs к себе — например, путём нажатия «Clone» на github. Либо — на любом другом сервере путём создания репозитория + клонирования нашего к себе на компьютер + push’а из локального репозитория в свой новый.
 +
* Удостовериваемся, что команда git remote -v show выводит ваш новый репозиторий (а не наш configs).
 +
* Создаём в новом configs '''собственный''' файл описания сборки — mediawiki4fuhrer.ini, и в нём пишем:
 +
<pre>
 +
; включаем нашу сборку
 +
[_params]
 +
include = mediawiki4intranet
 +
 +
; можно добавить свой префикс для репозиториев ($REPO будет заменено на имя репозитория)
 +
prefix.mysrv = git:http://myserver.office.ru/git/$REPO
 +
 +
; добавляем или переопределяем часть расширений
 +
[extensions/MySuperExtension]
 +
repo = github:viewfuhrer/MySuperExtension
 +
branch = master
 +
 +
; и так далее...
 +
</pre>
 +
* Скорее всего, вам потребуется версионировать и собственный вариант конфигурации (*Settings.php). Тут желательно тоже не трогать наш BaseSettings.php, а создать свой, включающий наш, и добавить его git add.
 +
 +
Далее внутри вашего нового configs запускаем команды:
 +
<code-bash>
 +
php repo.php update mediawiki4fuhrer rw
 +
git add mediawiki4fuhrer.ini mediawiki4fuhrer-index.ini
 +
git commit -m 'Создал свою сборку'
 +
git push
 +
</code-bash>
 +
 +
После этого вы можете работать со своей сборкой так же, как и с нашей (обновляя/добавляя/удаляя расширения). Чтобы удалить расширение, просто переопредите его параметр repo пустотой ("repo=").
 +
 +
{{NoteBox|Однако, для того, чтобы наши обновления попадали к вам, вам нужно время от времени сливать наши изменения со своими. То есть, время от времени вызывать команду {{cmd|git pull https://github.com/mediawiki4intranet/configs}}.}}
 +
 +
=== Создание архива / экспорт всех файлов в директорию ===
 +
 +
Следующая команда создаст копию сборки в директории <directory>, без системных директорий типа .git:
 +
* php repo.php export <directory>
 +
 +
Для создания архива со сборкой — просто закатайте полученную директорию в архив.
 +
 +
=== Troubleshooting ===
 +
 +
Если что-то пошло не так — с недавних пор repo.php должен вывести полный текст всех ошибок. Если этого не произошло — можно указать параметр '-j 1': <tt>php repo.php -j 1 update</tt>. Команды будут запущены последовательно и вы увидите полный вывод всех вызываемых команд.
  
 
== Зачем нужен собственный скрипт? ==
 
== Зачем нужен собственный скрипт? ==
  
Теоретически, вместо него можно было бы использовать просто подмодули Git’а (git submodules), но у них есть определённые минусы:
+
Теоретически, вместо repo.php можно было бы просто использовать подмодули Git’а (git submodules), но у них есть определённые минусы:
# Когда модулей под сотню — они '''медленные''', ибо они:
+
# Когда модулей под сотню — они '''медленные''', ибо:
 
#* Не умеют делать shallow клоны, всегда клонируют модули полностью.
 
#* Не умеют делать shallow клоны, всегда клонируют модули полностью.
 
#* Не поддерживают параллельное обновление.
 
#* Не поддерживают параллельное обновление.
 
# Сабмодули не могут работать с типичным расположением кода MediaWiki ''(если не клонировать репозиторий ядра)'', ибо:
 
# Сабмодули не могут работать с типичным расположением кода MediaWiki ''(если не клонировать репозиторий ядра)'', ибо:
 
#* Нельзя создать репозиторий, корень которого был бы submodule’ем.
 
#* Нельзя создать репозиторий, корень которого был бы submodule’ем.
#* Внутрь одного submodule нельзя поместить другой, не трогая репозиторий submodule.
+
#* Внутрь одного модуля нельзя поместить другой, не трогая его репозиторий.
#* Следовательно, репозиторий сборки должен являться клоном core с расширениями, подключёнными сабмодулями в <tt>extensions/ExtensionName</tt>. Изменения ядра в таком случае будут перемешиваться с изменениями модулей.
+
#* Следовательно, репозиторий сборки должен являться клоном core с расширениями, подключёнными сабмодулями в <tt>extensions/ExtensionName</tt>. Изменения ядра в таком случае будут перемешиваться с изменениями модулей. Так, кстати, и делает Wikimedia Foundation в своей сборке.
#: А это неудобно, так как хочется отделить репозиторий «сборки» от кода и дать возможность легко клонировать сборки, создавать свои сборки, дополненные какими-то расширениями и т. п.
+
#*: Но это неудобно, так как хочется отделить репозиторий «сборки» от кода и дать возможность легко клонировать сборки, создавать свои сборки, дополненные какими-то расширениями и т. п.
 +
#*: Разве что можно было уйти от стандартного MediaWiki’овского расположения кода и поместить core в отдельную подпапку, а extensions — вне core.
 
# Есть различные неудобства и недостатки функционала:
 
# Есть различные неудобства и недостатки функционала:
 
#* В .gitmodules нельзя указать желаемые ветки модулей (например, «хочу ParserFunctions REL1_20»). Опять-таки предполагается, что за версией модуля разработчик следит сам.
 
#* В .gitmodules нельзя указать желаемые ветки модулей (например, «хочу ParserFunctions REL1_20»). Опять-таки предполагается, что за версией модуля разработчик следит сам.
#* Неудобно переключать сабмодули между разными репозиториями — например, <tt>Wikimedia &rarr; наш_Github</tt> или <tt>наш_Github &rarr; ваш_форк</tt>.
+
#* Переключать один и тот же модуль между разными репозиториями нужно руками — например, <tt>Wikimedia &rarr; наш_Github</tt> или <tt>наш_Github &rarr; ваш_форк</tt>.
 
#* git archive не работает с сабмодулями — если хочется распространять архив с кодом всей сборки, нужно писать отдельный скрипт.
 
#* git archive не работает с сабмодулями — если хочется распространять архив с кодом всей сборки, нужно писать отдельный скрипт.
 
#* Не поддерживаются различные способы доступа к одному репозиторию, например http на чтение для всех и ssh на запись для разработчиков.
 
#* Не поддерживаются различные способы доступа к одному репозиторию, например http на чтение для всех и ssh на запись для разработчиков.
 +
#*: То есть, если хочется нормально push’ить с использованием ssh-ключа, то нужно заставлять '''всех''' клонировать всё исключительно по ssh (ссылка-то прямо в репозитории прописывается).
 +
#* Встречаются различные глюки. Например, «You are on a branch yet to be born» после неудачной попытки добавить submodule.
  
Часть этих проблем можно решить с помощью хелперов или bash-скриптов, однако мы решили сразу написать цельный инструмент.
+
Часть этих проблем можно было решить с помощью хелперов или bash-скриптов, однако мы решили сразу написать цельный инструмент.
  
== Возможности repo.php ==
+
== TODO ==
  
* Установка «сборок» на основе их описаний в ini-файлах, содержащих адреса репозиториев и имена требуемых веток
+
* Задание дополнительных remotes для устанавливаемых репозиториев. Например, 'wikimedia' для наших форков расширений.
* Поддержка shallow checkout, «быстрых» рабочих копий для установки (method=ro) и «медленных» для разработки (method=rw)
+
* Более гибкое задание readonly/readwrite — возможность клонирования части репозиториев как readonly, а части — как readwrite. Либо, возможность клонирования по https, а push’а по ssh. <s>Возможно, через те же remotes.</s> Оказывается, git сам умеет fetch’ить с одного адреса, а push’ить на другой!
* Быстрое обновление установленного кода на основе файла индекса, содержащего хеши ревизий
+
* Провентилировать идею безиндексной работы с помощью сервиса, который бы кэшировал ревизии репозиториев.
* Полное обновление всех модулей (что-то вроде git submodule foreach 'git pull')
+
* Параллельное обновление с красивым одновременным выводом состояния на экран с помощью escape-последовательностей (естественно, UNIX only)
+
* Поддержка произвольного расположения вытаскиваемых рабочих копий (в том числе друг внутри друга)
+
* Создание архива с полным кодом сборки
+
* Автоматическое переключение между разными репозиториями одного модуля
+
* Возможность легкого добавления поддержки нужных систем контроля версий (которая, правда, пока что не пригодилась)
+

Latest revision as of 16:07, 5 December 2013

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

Возможности 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=").

Note.svg Однако, для того, чтобы наши обновления попадали к вам, вам нужно время от времени сливать наши изменения со своими. То есть, время от времени вызывать команду git pull https://github.com/mediawiki4intranet/configs.

Создание архива / экспорт всех файлов в директорию

Следующая команда создаст копию сборки в директории <directory>, без системных директорий типа .git:

  • php repo.php export <directory>

Для создания архива со сборкой — просто закатайте полученную директорию в архив.

Troubleshooting

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

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

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

  1. Когда модулей под сотню — они медленные, ибо:
    • Не умеют делать shallow клоны, всегда клонируют модули полностью.
    • Не поддерживают параллельное обновление.
  2. Сабмодули не могут работать с типичным расположением кода MediaWiki (если не клонировать репозиторий ядра), ибо:
    • Нельзя создать репозиторий, корень которого был бы submodule’ем.
    • Внутрь одного модуля нельзя поместить другой, не трогая его репозиторий.
    • Следовательно, репозиторий сборки должен являться клоном core с расширениями, подключёнными сабмодулями в extensions/ExtensionName. Изменения ядра в таком случае будут перемешиваться с изменениями модулей. Так, кстати, и делает Wikimedia Foundation в своей сборке.
      Но это неудобно, так как хочется отделить репозиторий «сборки» от кода и дать возможность легко клонировать сборки, создавать свои сборки, дополненные какими-то расширениями и т. п.
      Разве что можно было уйти от стандартного MediaWiki’овского расположения кода и поместить core в отдельную подпапку, а extensions — вне 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-скриптов, однако мы решили сразу написать цельный инструмент.

TODO

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