Репозиторий darcs для DokuWiki

Исходными кодами DokuWiki управляют с помощью Darcs ¹⁾.

Darcs – это замена CVS. Darcs проще для изучения и использования, новый мощный подход позволяет помогает удовлетворить нужды современных распределенных софтверных проектов. Darcs – децентрализованная система, основанная на «теории заплаток» с корнями уходящими в квантовую механику. Darcs – свободное ПО, лицензированное под GPL.

Вместо того, чтобы повторять вещи где-то уже сказанные, я просто дам вам несколько ссылок:

• Download Darcs.
• Darcs Manual (The getting started chapter is an excellent starting point)
• Hints for CVS users

Для того, чтобы достать ²⁾ рабочую версию DokuWiki используйте следующую соманду (Она сама создаст директорию dokuwiki для вас):

darcs get --partial http://dev.splitbrain.org/darcs/dokuwiki

Для того, чтобы обновить существующую локальную версию, запустите в директории DokuWiki команду:

darcs pull

Когда вы создаете новый файл с исходным кодом, добавьте его в репозиторий darcs:

darcs add somenewfile

Когда вы закончите, запустите:

darcs record

При этом ваш локальный репозиторий darcs будет просканирован в поисках произведенных изменений и локально «зафиксирует»³⁾ ваши правки так, что они не потеряются при очередном «pull». В отличии от CVS, эта команда на самом деле не посылает никуда никакие файлы. Это напоминает «local tag» для вашей собственной копии кода.

Для того чтобы включить ваши правки в официальное дерево, создайте файл-заплатку:

darcs send -o my_doku_patch_file

Это создаст файл-заплатку, который может быть вручную отправлен в mailinglist.

• Всегда выполняйте операцию pull перед началом работы над новым патчем, это поможет избежать конфликтов.
• Никогда не используйте команду amend-record после того как отослали патч с помощью darcs send, это наверняка приведет к конфликту! Вместо этого, просто создайте другой патч, который исправляет первый.
• Убедитесь, что ваш редактор не изменяет окончания строк (с Unix-вого LF на DOS-овский CRLF), Это может привести к полной замене файла вместо маленькой заплатки, т.к. каждая строка в файле поменяется.
• Делайте отдельную заплатку для каждой отдельной «фичи». Когда работаете с двумя разными возможностями (например, языковое исправление и улучшение функции), запишите (record) две заплатки, по одной на каждую возможность. darcs упростит вам задачу, запросив, что включать в заплатку.

• Вы должны отослать заплатки в mailinglist и объяснить, что они делают и зачем.
• Не беспокойтесь о размере файла-заплатки. Заплатки darcs имеют свойство быть большими даже для небольших изменений. Пространство - дешево.
• Некоторые постовые клиенты и сервера плохо обходятся с текстовыми приложениями⁴⁾, нарушая хеши шифрования заплаток darcs. Для сохранения целостности архивируйте (zip, tar или gzip) ваши заплатки перед отправкой их по почте.

• Веб-интерфейс к репозиторию darcs доступен на http://dev.splitbrain.org/darcsweb/darcsweb.cgi?r=dokuwiki;a=summary

Из-за того, что каждая локальная копия ⁵⁾ имеет свой собственный репозиторий, люди могут хранить свои собственные модификации как наборы заплаток и имеют возможность обновлять исходники с «главного репозитория».

Так как же это работает на практике? Darcs не творит чудес, если вы изменили что-то в своем локальном репозитории и тоже самое было изменено в «главном репозитории» вы получите конфликт – с этим ничего не может поделать ни одна из RCS⁶⁾.

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

Например, если вы добавили немного HTML-кода в одну из функций в html.php, вы все еще можете применять официальные заплатки к html.php просто выполняя команду darcs pull.

Darcs - инструмент не только для разработчиков DokuWiki, он может быть использован для получения последней стабильной версии и для обновления до новой стабильной версии, когда она выйдет.

Для получения определенного релиза DokuWiki (замените yyyy-mm-dd на дату релиза, например, 2006-11-06):

darcs get --partial --tag="release yyyy-mm-dd" http://dev.splitbrain.org/darcs/dokuwiki

К сожалению, darcs содержит баг, который вызывает проблемы при совместном использовании –partial и –tag. До тех пор, пока этот баг не исправят, лучше избегать использования partial и просто использовать:

darcs get --tag="release yyyy-mm-dd" http://dev.splitbrain.org/darcs/dokuwiki

Для обновления до определенного релиза, до кандидата в релизы или до последнего релиза (стабильного):

darcs pull --tags "release yyyy-mm-dd" --all --quiet
darcs pull --tags "release candidate yyyy-mm-dd" --all --quiet
darcs pull --tags "release stable" --all --quiet

Параметры –all –quiet гарантируют, что все заплатки будут применены, и darcs сделает это успешно, и сделает свою работу без множества сообщений.

Если вы сделали свои собственные изменения в основном коде DokuWiki, будет лучше опустить ключи –all –quiet и принимать каждую заплатку интерактивно, т.е.

darcs pull --tags "release yyyy-mm-dd"
darcs pull --tags "release candidate yyyy-mm-dd"
darcs pull --tags "release stable"

В конце процесса наложения заплаток Darcs даст вам знать, если произошли какие-либо конфликты между вашими изменениями и заплатками, примененными для обновления до новой версии. Вы можете после этого проверить проблемные файлы и внести необходимые изменения.

Вы можете использоваться следующую команду для отслеживания изменений, внесенных вами в DokuWiki:

darcs whatsnew

При интерактивном запуске команда revert проделает что-то подобное же и даст вам возможность удалить ваши правки если они больше не нужны.

Итак, почему выбрал Darcs, а не CVS, Subversion или arch?

Darcs имеет по моему мнению несколько преимуществ:

• она не требует специального сервера для анонимного доступа только на чтение – достаточно любого HTTP-сервера
• она может управлять директориями (подобно SVN и arch)
• она полностью распределена, каждый локальная копия является своим собственным репозиторием (подобно arch)
• никаких сложных схем имен не нужно (как в arch)
• независимые наборы заплаток (см. ниже)
• легко делать свои добавления (contribution) или применять чужие (через darcs send)

Хотя есть несколько неудобств:

• она немного глючная (хотя не критично)
• она еще относительно малоизвестна

Что люблю больше всего, это наборы заплаток. Из-за того, что каждая локальная копия (checkout) является собственным репозиторием, люди могут держать свои собственные модификации как наборы заплаток, и все еще могут обновлять свой код с моего «главного репозитория», см. секции выше