~bzr-pqm/bzr/bzr.dev

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
===============================
Работа в централизованном стиле
===============================

.. sectnum::


Обзор
=====

Этот документ описывает один из возможных подходов к использованию
Bazaar_. А именно, использование распределенной системы контроля версий
Bazaar_, в централизованном стиле. Bazaar_ разработана, что бы быть гибкой
и допускать различные подходы к работе, начиная от полностью
децентрализованного, до практически централизованного. Подход описанный
здесь позволяет новым пользователям проще вникнуть в более продвинутое
использование Bazaar_ и смешивать централизованные и децентрализованные
операции.

В общем случае, данный документ интересен для пользователей переходящих с
централизованных систем, таких как CVS, или Subversion. В таких системах
обычно есть единственный центральный сервер на котором хранится код
проекта и участники команды работают над этим кодом, синхронизируя свою
работу. Такой режим так же подходит для разработчика-одиночки,
работающего на нескольких различных машинах.

.. _Bazaar: http://bazaar-vcs.org

.. 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://bazaar-vcs.org/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://bazaar-vcs.org/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