← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to doc/shared_repository_layouts.txt

Merge the 0.17 fixes back into bzr.dev

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/shared_repository_layouts.txt
1
 
Advanced shared repository layouts
2
 
==================================
3
 
 
4
 
Bazaar is designed to give you flexibility in how you layout branches inside a shared repository.
 
1
=======================
 
2
SharedRepositoryLayouts
 
3
=======================
 
4
 
 
5
.. sectnum::
 
6
 
 
7
Bazaar is designed to give you flexibility in how you layout branches inside a shared repository. 
5
8
This flexibility allows users to tailor Bazaar to their workflow,
6
9
but it also leads to questions about what is a "good" layout.
7
10
We present some alternatives and give some discussion about the benefits of each.
11
14
and in most of the layouts this naming convention is preserved. Some would call this
12
15
"``mainline``" or "``dev``", and people from CVS often refer to this as "``HEAD``".
13
16
 
 
17
.. contents::
 
18
 
14
19
 
15
20
"SVN-Style" (``trunk/``, ``branches/``)
16
 
---------------------------------------
 
21
=======================================
17
22
 
18
 
Most people coming from SVN will be familiar with their "standard" project layout.
 
23
Most people coming from SVN will be familiar with their "standard" project layout. 
19
24
Which is to layout the repository as::
20
25
 
21
26
  repository/       # Overall repository
27
32
       +- release-X # A branch specific to mark a given release version
28
33
          ...
29
34
 
30
 
With Bazaar, that is a perfectly reasonable layout.
31
 
It has the benefit of being familiar to people coming from SVN,
 
35
With Bazaar, that is a perfectly reasonable layout. 
 
36
It has the benefit of being familiar to people coming from SVN, 
32
37
and making it clear where the development focus is.
33
38
 
34
 
When you have multiple projects in the same repository,
 
39
When you have multiple projects in the same repository, 
35
40
the SVN layout is a little unclear what to do.
36
41
 
37
42
 
52
57
       +- branches/      # Container for project2 branches
53
58
 
54
59
 
55
 
This also works with Bazaar.
56
 
However, with Bazaar repositories are cheap to create
 
60
This also works with Bazaar. 
 
61
However, with Bazaar repositories are cheap to create 
57
62
(a simple ``bzr init-repo`` away), and their primary benefit is when the
58
63
branches share a common ancestry.
59
64
 
64
69
     +- branches/      # A container directory
65
70
         +- foo/       # Branch for developing feature foo of project1
66
71
           ...
67
 
 
 
72
    
68
73
    project2/          # A repository for project2
69
74
     +- trunk/         # Mainline for project2
70
75
     +- branches/      # Container for project2 branches
100
105
        +- project1-foo/  # Branch 'foo' of project1
101
106
        +- project2-bar/  # Branch 'bar' of project2
102
107
 
103
 
I believe the reason for this in SVN, is so that someone
 
108
I believe the reason for this in SVN, is so that someone 
104
109
can checkout all of "``trunk/``" and get the all the mainlines for all projects.
105
110
 
106
111
This layout can be used for Bazaar, but it is not generally recommended.
107
112
 
108
 
 1) ``bzr branch/checkout/get`` is a single branch at a time.
 
113
 1) ``bzr branch/checkout/get`` is a single branch at a time. 
109
114
    So you don't get the benefit of getting all mainlines with a single command. [1]_
110
115
 
111
 
 2) It is less obvious of whether ``repository/trunk/foo`` is the ``trunk`` of project
 
116
 2) It is less obvious of whether ``repository/trunk/foo`` is the ``trunk`` of project 
112
117
    ``foo`` or it is just the ``foo`` directory in the ``trunk`` branch.
113
 
    Some of this confusion is due to SVN, because it uses the same "namespace"
 
118
    Some of this confusion is due to SVN, because it uses the same "namespace" 
114
119
    for files in a project that it uses for branches of a project.
115
120
    In Bazaar, there is a clear distinction of what files make up a project, versus
116
121
    the location of the Branch. (After all, there is only one ``.bzr/`` directory per branch,
125
130
 
126
131
 
127
132
Nested Style (``project/branch/sub-branch/``)
128
 
---------------------------------------------
 
133
=============================================
129
134
 
130
135
Another style with Bazaar, which is not generally possible in SVN
131
136
is to have branches nested within each-other.
148
153
      +- 1.0/
149
154
          +- 1.1.1/
150
155
 
151
 
The idea with this layout is that you are creating a hierarchical layout for branches.
 
156
The idea with this layout is that you are creating a hierarchical layout for branches. 
152
157
Where changes generally flow upwards in the namespace. It also gives people a little
153
158
corner of the namespace to work on their stuff.
154
159
One nice feature of this layout, is it makes branching "cheaper" because it gives you
162
167
  bzr branch http://host/repository/project/branches/joe-feature-foo-bugfix-10/
163
168
 
164
169
Versus::
165
 
 
 
170
  
166
171
  bzr branch http://host/project/joe/foo/bugfix-10
167
172
 
168
173
 
175
180
  joe-bugfix-13/
176
181
  joe-frizban/
177
182
 
178
 
Versus having these broken out by developer.
 
183
Versus having these broken out by developer. 
179
184
If the number of branches are small, ``branches/`` has the nice advantage
180
185
of being able to see all branches in a single view.
181
186
If the number of branches is large, ``branches/`` has the distinct disadvantage
183
188
branch you are interested in, when there are 100 branches to look through).
184
189
 
185
190
Nested branching seems to scale better to larger number of branches.
186
 
However, each individual branch is less discoverable.
 
191
However, each individual branch is less discoverable. 
187
192
(eg. "Is Joe working on bugfix 10 in his feature foo branch, or his feature bar branch?")
188
193
 
189
194
One other small advantage is that you can do something like::
192
197
  or
193
198
   bzr branch http://host/project/release/1/1/2
194
199
 
195
 
To indicate release 1.1.1 and 1.1.2. This again depends on how many releases you have
 
200
To indicate release 1.1.1 and 1.1.2. This again depends on how many releases you have 
196
201
and whether the gain of splitting things up outweighs the ability to see more at a glance.
197
202
 
198
203
 
199
204
Sorted by Status (``dev/``, ``merged/``, ``experimental/``)
200
 
-----------------------------------------------------------
 
205
===========================================================
201
206
 
202
207
One other way to break up branches is to sort them by their current status.
203
208
So you would end up with a layout something like::
217
222
It lets you see what branches are actively being developed on, which is usually
218
223
only a small number, versus the total number of branches ever created.
219
224
Old branches are not lost (versus deleting them), but they are "filed away",
220
 
such that the more likely you are to want a branch the easier it is to find.
 
225
such that the more likely you are to want a branch the easier it is to find. 
221
226
(Conversely, older branches are likely to be harder to find).
222
227
 
223
228
The biggest disadvantage with this layout, is that branches move around.
237
242
that could be changed.
238
243
This is actually how `Launchpad`_ allows you to ``bzr checkout https://launchpad.net/bzr``.
239
244
Effectively a ``BranchReference`` is a symlink, but it allows you to reference any other URL.
240
 
If it is extended to support relative references, it would even work over http, sftp,
 
245
If it is extended to support relative references, it would even work over http, sftp, 
241
246
and local paths.
242
247
 
243
248
.. _Launchpad: https://launchpad.net
244
249
 
245
250
 
246
251
Sorted by date/release/etc (``2006-06/``, ``2006-07/``, ``0.8/``, ``0.9``)
247
 
--------------------------------------------------------------------------
 
252
==========================================================================
248
253
 
249
254
Another method of allowing some scalability while also allowing the
250
 
browsing of "current" branches. Basically, this works on the assumption
 
255
browsing of "current" branches. Basically, this works on the assumption 
251
256
that actively developed branches will be "new" branches, and older branches
252
257
are either merged or abandoned.
253
258
 
292
297
The general idea is that by targeting a release, you can look at what branches are
293
298
waiting to be merged. It doesn't necessarily give you a good idea of what the
294
299
state of the branch (is it in development or finished awaiting review).
295
 
It also has a history-hiding effect, and otherwise has the same benefits
296
 
and deficits as a date-based sorting.
 
300
It also has a history-hiding effect, and otherwise has the same benefits 
 
301
and deficits as a date-based sorting. 
297
302
 
298
303
 
299
304
Simple developer naming (``project/joe/foo``, ``project/barry/bar``)
300
 
--------------------------------------------------------------------
 
305
====================================================================
301
306
 
302
307
Another possibly layout is to give each developer a directory, and then
303
308
have a single sub-directory for branches. Something like::
347
352
 
348
353
 
349
354
Summary
350
 
-------
 
355
=======
351
356
 
352
357
In the end, no single naming scheme will work for everyone. It depends a lot on
353
358
the number of developers, how often you create a new branch, what sort of