← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to doc/en/user-guide/shared_repository_layouts.txt

  • Committer: Andrew Bennetts
  • Date: 2009-12-03 05:57:41 UTC
  • mfrom: (4857 +trunk)
  • mto: This revision was merged to the branch mainline in revision 4869.
  • Revision ID: andrew.bennetts@canonical.com-20091203055741-vmmg0fmjgjw2pwvu
Merge lp:bzr.

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/en/user-guide/shared_repository_layouts.txt
1
1
Advanced shared repository layouts
2
2
==================================
3
3
 
4
 
Bazaar is designed to give you flexibility in how you layout branches inside a shared repository. 
 
4
Bazaar is designed to give you flexibility in how you layout branches inside a shared repository.
5
5
This flexibility allows users to tailor Bazaar to their workflow,
6
6
but it also leads to questions about what is a "good" layout.
7
7
We present some alternatives and give some discussion about the benefits of each.
15
15
"SVN-Style" (``trunk/``, ``branches/``)
16
16
---------------------------------------
17
17
 
18
 
Most people coming from SVN will be familiar with their "standard" project layout. 
 
18
Most people coming from SVN will be familiar with their "standard" project layout.
19
19
Which is to layout the repository as::
20
20
 
21
21
  repository/       # Overall repository
27
27
       +- release-X # A branch specific to mark a given release version
28
28
          ...
29
29
 
30
 
With Bazaar, that is a perfectly reasonable layout. 
31
 
It has the benefit of being familiar to people coming from SVN, 
 
30
With Bazaar, that is a perfectly reasonable layout.
 
31
It has the benefit of being familiar to people coming from SVN,
32
32
and making it clear where the development focus is.
33
33
 
34
 
When you have multiple projects in the same repository, 
 
34
When you have multiple projects in the same repository,
35
35
the SVN layout is a little unclear what to do.
36
36
 
37
37
 
52
52
       +- branches/      # Container for project2 branches
53
53
 
54
54
 
55
 
This also works with Bazaar. 
56
 
However, with Bazaar repositories are cheap to create 
 
55
This also works with Bazaar.
 
56
However, with Bazaar repositories are cheap to create
57
57
(a simple ``bzr init-repo`` away), and their primary benefit is when the
58
58
branches share a common ancestry.
59
59
 
64
64
     +- branches/      # A container directory
65
65
         +- foo/       # Branch for developing feature foo of project1
66
66
           ...
67
 
    
 
67
 
68
68
    project2/          # A repository for project2
69
69
     +- trunk/         # Mainline for project2
70
70
     +- branches/      # Container for project2 branches
100
100
        +- project1-foo/  # Branch 'foo' of project1
101
101
        +- project2-bar/  # Branch 'bar' of project2
102
102
 
103
 
I believe the reason for this in SVN, is so that someone 
 
103
I believe the reason for this in SVN, is so that someone
104
104
can checkout all of "``trunk/``" and get the all the mainlines for all projects.
105
105
 
106
106
This layout can be used for Bazaar, but it is not generally recommended.
107
107
 
108
 
 1) ``bzr branch/checkout/get`` is a single branch at a time. 
 
108
 1) ``bzr branch/checkout/get`` is a single branch at a time.
109
109
    So you don't get the benefit of getting all mainlines with a single command. [1]_
110
110
 
111
 
 2) It is less obvious of whether ``repository/trunk/foo`` is the ``trunk`` of project 
 
111
 2) It is less obvious of whether ``repository/trunk/foo`` is the ``trunk`` of project
112
112
    ``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" 
 
113
    Some of this confusion is due to SVN, because it uses the same "namespace"
114
114
    for files in a project that it uses for branches of a project.
115
115
    In Bazaar, there is a clear distinction of what files make up a project, versus
116
116
    the location of the Branch. (After all, there is only one ``.bzr/`` directory per branch,
148
148
      +- 1.0/
149
149
          +- 1.1.1/
150
150
 
151
 
The idea with this layout is that you are creating a hierarchical layout for branches. 
 
151
The idea with this layout is that you are creating a hierarchical layout for branches.
152
152
Where changes generally flow upwards in the namespace. It also gives people a little
153
153
corner of the namespace to work on their stuff.
154
154
One nice feature of this layout, is it makes branching "cheaper" because it gives you
162
162
  bzr branch http://host/repository/project/branches/joe-feature-foo-bugfix-10/
163
163
 
164
164
Versus::
165
 
  
 
165
 
166
166
  bzr branch http://host/project/joe/foo/bugfix-10
167
167
 
168
168
 
175
175
  joe-bugfix-13/
176
176
  joe-frizban/
177
177
 
178
 
Versus having these broken out by developer. 
 
178
Versus having these broken out by developer.
179
179
If the number of branches are small, ``branches/`` has the nice advantage
180
180
of being able to see all branches in a single view.
181
181
If the number of branches is large, ``branches/`` has the distinct disadvantage
183
183
branch you are interested in, when there are 100 branches to look through).
184
184
 
185
185
Nested branching seems to scale better to larger number of branches.
186
 
However, each individual branch is less discoverable. 
 
186
However, each individual branch is less discoverable.
187
187
(eg. "Is Joe working on bugfix 10 in his feature foo branch, or his feature bar branch?")
188
188
 
189
189
One other small advantage is that you can do something like::
192
192
  or
193
193
   bzr branch http://host/project/release/1/1/2
194
194
 
195
 
To indicate release 1.1.1 and 1.1.2. This again depends on how many releases you have 
 
195
To indicate release 1.1.1 and 1.1.2. This again depends on how many releases you have
196
196
and whether the gain of splitting things up outweighs the ability to see more at a glance.
197
197
 
198
198
 
217
217
It lets you see what branches are actively being developed on, which is usually
218
218
only a small number, versus the total number of branches ever created.
219
219
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. 
 
220
such that the more likely you are to want a branch the easier it is to find.
221
221
(Conversely, older branches are likely to be harder to find).
222
222
 
223
223
The biggest disadvantage with this layout, is that branches move around.
237
237
that could be changed.
238
238
This is actually how `Launchpad`_ allows you to ``bzr checkout https://launchpad.net/bzr``.
239
239
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, 
 
240
If it is extended to support relative references, it would even work over http, sftp,
241
241
and local paths.
242
242
 
243
243
.. _Launchpad: https://launchpad.net
247
247
--------------------------------------------------------------------------
248
248
 
249
249
Another method of allowing some scalability while also allowing the
250
 
browsing of "current" branches. Basically, this works on the assumption 
 
250
browsing of "current" branches. Basically, this works on the assumption
251
251
that actively developed branches will be "new" branches, and older branches
252
252
are either merged or abandoned.
253
253
 
292
292
The general idea is that by targeting a release, you can look at what branches are
293
293
waiting to be merged. It doesn't necessarily give you a good idea of what the
294
294
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. 
 
295
It also has a history-hiding effect, and otherwise has the same benefits
 
296
and deficits as a date-based sorting.
297
297
 
298
298
 
299
299
Simple developer naming (``project/joe/foo``, ``project/barry/bar``)