~bzr-pqm/bzr/bzr.dev

===============================

Работа в централизованном стиле

===============================

.. sectnum::

Обзор

=====

Этот документ описывает один из возможных подходов к использованию

Bazaar_. А именно, использование распределенной системы контроля версий

Bazaar_, в централизованном стиле. Bazaar_ разработана, что бы быть гибкой

и допускать различные подходы к работе, начиная от полностью

децентрализованного, до практически централизованного. Подход описанный

здесь позволяет новым пользователям проще вникнуть в более продвинутое

использование Bazaar_ и смешивать централизованные и децентрализованные

операции.

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

централизованных систем, таких как CVS, или Subversion. В таких системах

обычно есть единственный центральный сервер на котором хранится код

проекта и участники команды работают над этим кодом, синхронизируя свою

работу. Такой режим так же подходит для разработчика-одиночки,

работающего на нескольких различных машинах.

.. _Bazaar: http://bazaar.canonical.com

.. contents::

        Содержание

Начальные установки

===================

В самом начале, для более удобной работы с Bazaar_, желательно осуществить

достаточно простые шаги по настройке.

Настройка e-mail пользователя

-----------------------------

Строка идентифицирующая пользователя сохраняется при каждой фиксации. Хотя

она не обязательно должна быть аккуратной или уникальной она будет

использоваться в сообщениях журнала и аннотациях, таким образом лучше что

бы она была похожа на что-то реальное.

::

   % bzr whoami "Иван Пупкин <ivan@pupkin.ru>"

Настройка локального репозитория

--------------------------------

В общем случае ветки Bazaar_ копируют полную историю изменений вместе с

собой, что, кстати, позволяет работать в полностью децентрализованном

стиле. Как оптимизация для связанных веток возможно объединять их

хранилища таким образом, что отпадает необходимость в копировании полной

истории изменений при создании новой ветки.

Лучший способ сделать это - создать `Разделяемый репозиторий`_. В общем

случае, ветки будут разделять хранилище если они находятся в подкаталоге

этого репозитория. Давайте создадим `Разделяемый репозиторий`_ в нашем

домашнем каталоге и таким образом все ветки которые мы будем создавать

под ним будут разделять хранилище истории.

::

  % bzr init-repo --trees ~

Настройка удаленного репозитория

--------------------------------

Во многих случаях нужно создавать место где данные хранятся отдельно от

рабочего каталога. Такой подход необходим для централизованных систем

(CVS/SVN). Обычно эти каталоги находятся на различных машинах, хотя и не

всегда. На самом деле это достаточно хороший подход, особенно в рабочей

среде. Так как здесь существует центральная точка, где могут быть сохранены

все данные и даже если что-то случится с машиной разработчика

зафиксированная работа не будет потеряна.

Давайте создадим разделяемое место для нашего проекта на удаленной машине

и назовем его ``centralhost``. Мы снова используем `Разделяемый

репозиторий`_ для оптимизации использования дисков.

::

  % bzr init-repo --no-trees sftp://centralhost/srv/bzr/

Можно рассматривать этот шаг как похожий на установку CVSROOT, или

репозитория Subversion. Опция ``--no-trees`` указывает Bazaar не

создавать рабочий каталог в репозитории. Нам это подходит, т.к. никто

не будет напрямую что-то изменять на ветках в центральном репозитории.

Миграция рабочего проекта в Bazaar

==================================

Теперь, когда у нас есть репозиторий давайте создадим проект под контролем

версий. В большинстве случаев у вас уже есть какой-то код с которым вы

работаете и для хранения которого вы хотели бы использовать Bazaar_. Если

код изначально уже был под контролем версий существует много способов

конвертировать проект в Bazaar_ без потери истории изменений. Но эти

способы находятся вне тем рассматриваемых в данном документе. Смотрите

`Отслеживание изменений на основной ветке`_ для некоторых способов (секция

"Конвертирование и сохранение истории").

.. _Отслеживание изменений на основной ветке: http://wiki.bazaar.canonical.com/TrackingUpstream

..

   TODO: На самом деле нам нужен другой документ для описания

   конвертирования проекта. Но пока ссылка выше - это лучшее.

Разработчик 1: Создание первой ревизии

--------------------------------------

Сначала нам нужно создать ветку в нашем удаленном репозитории, там где мы

хотели бы хранить наш проект. Допустим, что у нас уже есть проект "sigil",

который мы хотели бы хранить под контролем версий.

::

  % bzr init sftp://centralhost/srv/bzr/sigil

Это можно рассматривать как ветку "HEAD" в терминах CVS, или как "trunk" в

терминах Subversion. Назовем это веткой разработки ``dev``.

Я предпочитаю работать в подкаталоге моего домашнего каталога, что бы

избегать коллизий со всеми другими файлами которые в ней находятся. Также

нам понадобится каталог для проекта где мы сможем хранить различные ветки

проекта над которыми работаем.

::

  % cd ~

  % mkdir work

  % cd work

  % mkdir sigil

  % cd sigil

  % bzr checkout sftp://centralhost/srv/bzr/sigil dev

  % cd dev

  % cp -ar ~/sigil/* .

  % bzr add

  % bzr commit -m "Первый импорт Sigil"

Выше мы создали пустую ветку ``/sigil`` на ``centralhost`` и затем

загрузили эту пустую ветку на нашу рабочую машину что бы добавить файлы из

нашего старого проекта. Есть много способов настроить свой рабочий

каталог, но шаги выше упрощают дальнейшую работу с ветками для работы

над ошибками, или новыми функциями. И одна из наиболее сильных сторон

Bazaar_ - это именно отличная работа с ветками.

На этом этапе, т.к. мы создали рабочую копию (checkout) удаленной ветки,

все фиксации которые будут сделаны в ``~/work/sigil/dev/`` будут

автоматически сохранены и локально и на ``centralhost``.

Разработчик N: Получение рабочей копии проекта

----------------------------------------------

Так как первый разработчик проделал всю работу по созданию проекта все

остальные разработчики могут просто получить рабочую копию ветки. Хотя

**они все еще должны следовать** разделам `Настройка e-mail пользователя`_ и

`Настройка локального репозитория`_.

Получим рабочую копию текущего дерева разработки::

  % cd ~/work/sigil

  % bzr checkout sftp://centralhost/srv/bzr/sigil dev

Теперь, когда два человека имею рабочую копию

``sftp://centralhost/srv/bzr/sigil`` будут ситуации когда одна из копий

будет не синхронизирована с текущей версией. Во время фиксации Bazaar_

проинформирует пользователя об этом и не допустит фиксации. Для получения

последних изменений нужно использовать ``bzr update``. Эта команда может

потребовать разрешения конфликтов если были изменены одни и те же файлы.

Разработка на отдельных ветках

==============================

До этого момента все работали и фиксировали изменения на одну и ту же

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

иметь дело с изменениями других разработчиков. Так же если один

разработчик фиксирует что-то, что приводит к ошибкам, то после

синхронизации эта проблема коснется каждого.

Обычно лучше вести разработку на различных ветках и затем, как только

изменения достаточно стабильны, интегрировать их обратно на основную

ветку. Это одно из наибольших изменений по сравнению с работой в CVS/SVN.

Обе эти системы позволяют работать с отдельными ветками, но их алгоритмы

объединения достаточно слабы и поэтому с ними сложно держать все

синхронизировано. Bazaar_ отслеживает что уже было объединено и может даже

прикладывать изменения к файлам которые были переименованы.

Создание и работа на новой ветке

--------------------------------

Мы бы хотели, что бы наши изменения были доступны другим даже если они

пока еще не закончены. Таким образом мы создадим новую публичную ветку на

``centralhost`` и будем отслеживать ее локально.

::

  % cd ~/work/sigil

  % bzr branch sftp://centralhost/srv/bzr/sigil \

               sftp://centralhost/srv/bzr/sigil/doodle-fixes

  % bzr checkout sftp://centralhost/srv/bzr/sigil/doodle-fixes doodle-fixes

  % cd doodle-fixes

Теперь у нас есть место где мы можем исправлять все ошибки для ``doodle``.

И мы не будем прерывать никого кто работает над другими частями кода. Так

как у нас есть рабочая копия (checkout) все фиксации которые мы делаем на

``~/work/sigil/doodle-fixes/`` так же появятся и на ``centralhost``.

[#nestedbranches]_ Также возможно, что бы два разработчика совместно

работали над одной из этих веток, так же как они совместно работают над

веткой ``dev``. [#cbranch]_

.. [#nestedbranches] Может показаться странным иметь ветку в подкаталоге

   другой ветки. Но это нормально, можно думать об этом как о

   иерархическом пространстве имен где вложенная ветка является

   производной от внешней ветки.

.. [#cbranch] Когда используется множество независимых веток каждый раз

   набирать полный URL занимает много времени. Мы рассматриваем различные

   методы, что бы обойти это, например псевдонимы для веток и т.п. Но пока

   плагин bzrtools_ предоставляет команду ``bzr cbranch``. Эта команда на

   основе базовой ветки создает новую публичную ветку и рабочую копию этой

   ветки всего одной командой. Конфигурирование ``cbranch`` не входит в

   рамки описания этого документа, но финальная команда выглядит следующим

   образом:

   ::

   % bzr cbranch dev my-feature-branch

.. _bzrtools: http://wiki.bazaar.canonical.com/BzrTools

Объединение изменений обратно

-----------------------------

Когда решено что некоторые изменения из ``doodle-fixes`` готовы для

объединения на основную ветку нужно просто сделать следующее::

  % cd ~/work/sigil/dev

  % bzr merge ../doodle-fixes

Теперь изменения доступны на ветке ``dev``, но они пока еще не были

зафиксированы. В этот момент нужно просмотреть финальные изменения и

проверить, что код компилируется и проходят все тесты. Команды ``bzr

status`` и ``bzr diff`` хорошие инструменты для этого. Так же нужно

разрешить возможные конфликты. Bazaar_ не допустит фиксации пока не будут

разрешены все конфликты. В этом случае вы случайно не зафиксируете маркеры

конфликта. Команда ``bzr status`` покажет конфликты и изменения, или можно

использовать ``bzr conflicts`` что бы увидеть только конфликты.

Используйте ``bzr resolve file/name``, или ``bzr resolve --all`` как

только конфликты были разрешены. [#resolve]_ Если существуют конфликты

которые особенно сложно разрешить можно использовать команду ``bzr

remerge``. Эта команда позволит использовать другие алгоритмы объединения

и также позволит увидеть строки оригинального кода (``--show-base``).

.. [#resolve] Некоторые системы позволяют разрешать конфликты как часть

   процесса объединения. Мы обнаружили, что обычно проще разрешать

   конфликты когда можно просматривать полное дерево, а не только

   отдельные файлы. Это дает намного больше контекста и также позволяет

   запускать тесты когда проблема будет решена.

Рекомендации по созданию веток

------------------------------

Один из часто используемых способов работы с набором веток - это дать

каждому разработчику свою собственную ветку и собственное место для работы

на центральном сервере. Это можно сделать так::

  % bzr branch sftp://centralhost/srv/bzr/sigil \

               sftp://centralhost/srv/bzr/sigil/user-a

  % bzr branch sftp://centralhost/srv/bzr/sigil \

               sftp://centralhost/srv/bzr/sigil/user-b

Это дает каждому разработчику собственную ветку для работы. И они смогут

легко создать новые ветки с помощью [#cbranch]_

::

  % bzr branch sftp://centralhost/srv/bzr/sigil/user-a \

               sftp://centralhost/srv/bzr/sigil/user-a/feature

  % cd ~/work/sigil

  % bzr checkout sftp://centralhost/srv/bzr/sigil/user-a/feature myfeature

Глоссарий

=========

Разделяемый репозиторий

-----------------------

Bazaar_ поддерживает концепцию "Разделяемый репозиторий". Эта концепция

похожа на традиционные концепции репозиториев в других системах контроля

версий, таких как CVS, или Subversion. Например, в Subversion у вас есть

удаленный репозиторий, где хранится вся история и локально история не

хранится, а хранится только рабочая копия файлов. Конечно "Разделяемый" в

данном контексте значит, что он разделен между ветками. Он *может* быть

разделен между людьми, но отдельные ветки также могут быть разделены между

людьми.

В Bazaar_ термин "Разделяемый репозиторий" - это место где несколько веток

могут *разделять* их историю ревизий. Что бы поддерживать

децентрализованную схему работы каждая ветка может хранить свою

собственную историю ревизий. Но часто это не эффективно, т.к. зависимые

ветки разделяют историю и они могут так же разделять и хранилище истории.

..

   vim: tw=74 ft=rst spell spelllang=en_us