« back to all changes in this revision
Viewing changes to doc/developers/colocated-branches.txt
- browse files at revision 5141.3.1
- compare with another revision
- compare with revision 5141.3.2
- download diff
- download tarball
- view history from revision 5141.3.1
- Committer: Jelmer Vernooij
- Date: 2010-04-10 00:37:38 UTC
- mto: (5147.4.2 more-colo)
- mto: This revision was merged to the branch mainline in revision 5148.
- Revision ID: jelmer@samba.org-20100410003738-mv5jepxodis0hr28
Update the colocated branches spec based on the discussion in Strasbourg.
- files modified:
- doc/developers/colocated-branches.txt
added
removed
doc/developers/colocated-branches.txt
6
6
branches there are several situations where it might be useful to also
7
7
support multiple branches under the same file system directory.
8
8
9
There is an experimental implementation for Bazaar available as a plugin
10
at http://people.samba.org/bzr/jelmer/bzr-local-branches/trunk. This was
11
the original proof-of-concept and doesn't yet use the API documented
12
here.
13
14
9
Rationale
15
10
---------
16
11
46
41
UI Changes
47
42
~~~~~~~~~~
48
43
49
Bazaar URLs need to have some way to specify a colocated branch other
50
than the current HEAD. Several options have been discussed, each with
51
its own advantages and disadvantages: This was discussed on the mailing
52
list, most notably the use of a ";branch=NAME" suffix as well as a special
53
separation character (+, =, etc), but no final conclusion was reached.
54
55
https://lists.ubuntu.com/archives/bazaar/2008q4/050105.html
44
Bazaar URLs need to have some way to address colocated branches in
45
directories that contain multiple branches.
46
47
Per RFC3986 we have picked the comma (",") to allow the specification of
48
colocated branch names. Comma's in path names would have to be
49
urlencoded at first to avoid ambiguity, though perhaps it would be
50
possible to support heuristics later when interpreting user-specified URLs.
51
52
An example URL would be:
53
54
bzr://bazaar.launchpad.net/~jelmer/bzr/bzr.dev,colo-urls
55
56
The segment after the comma will initially be interpreted as a colocated
57
branch name but we would like to keep the option option to allow
58
key=value style specifications in the future and DWIM for segments that
59
do not contain an =.
60
61
Control directories will also have the notion of an "active" branch. This is
62
the branch that is being used by a working tree, if present and the branch
63
that will be used if no explicit colocated branch is specified. The
64
active branch support makes it easier to deal with existing bzrdirs and
65
is useful when accessing foreign control directories that have the concept
66
as well.
67
68
A new command 'bzr rmbranch' needs to be added to make it possible to
69
remove colocated branches, as this won't be possible by simple
70
directory removal, at least not of a user-visible directory.
56
71
57
72
Code Changes
58
73
~~~~~~~~~~~~
59
74
60
BzrDir should support a BzrDir.supports_colocated_branches() call as well as
61
BzrDir.colocated_branches property that contains a colocated branch container,
62
that can be used to add / remove colocated branches as well as change the
63
currently active colocated branch.
64
65
::
66
67
class ColocatedBranchContainer(object):
68
69
def get_active_branch_name(self):
70
"""Returns the name of the currently active branch.
71
72
This can be None if no branch is currently active.
73
"""
74
75
def get_active_branch(self):
76
"""Returns the currently active branches' Branch object."""
77
78
def get_branch(self, name):
79
"""Returns the Branch object for the specified branch."""
80
81
def available_branches(self):
82
"""Returns a set with the names of the available branches."""
83
84
def set_active_branch(self, name):
85
"""Set the currently active branch."""
86
87
def destroy_branch(self, name):
88
"""Destroy the specified branch.
89
90
This will remove the branch from disk."""
91
92
If the particular BzrDir implementation doesn't support colocated
93
branches, it can just return a dummy container that just contains a
94
HEAD branch.
95
96
Looms can of course return a container with all their threads.
97
98
BzrDir.find_branches() should take into account the colocated branches
99
when iterating over its branches.
75
BzrDirFormat will need a supports_colocated_branches property that
76
indicates whether a format supports the creation, removal and accessing of
77
colocated branches.
78
79
Several methods on BzrDir will need to be updated to take an option branch_name
80
parameter. If this parameter is not specified or None, the active branch
81
will be used.
82
83
The methods that will have to be extended are:
84
85
* BzrDir.open_branch()
86
* BzrDir.create_branch()
87
* BzrDir.destroy_branch()
88
* BzrDir.get_branch_transport()
89
90
* BranchFormat.initialise()
91
* BranchFormat.open()
92
93
A new BzrDir.list_branches() method will return all colocated branches
94
present in a control directory.
95
96
Any URL interpreting methods (e.g. Branch.open) will need to be updated
97
to extract a colocated branch name and need to pass that into the
98
relevant methods.
99
100
Existing callers of BzrDir.{create,open,destroy}_branch() need to
101
be updated to pass in branch names and optionally be changed to use
102
BzrDir.list_branches().
100
103
101
104
Schema Changes
102
105
--------------
108
111
Eventually, Bazaar could easily support colocated branches by just
109
112
creating a new branch transport for each colocated branch and have a
110
113
"regular" branch live there. This would require something like
111
BzrDirMeta2 though.
112
113
Unresolved Issues
114
-----------------
115
116
* What about colocated looms ?
117
* What character to use to name colocated branches in URLs?
118
114
BzrDirMeta2 though. An example of this is implemented in the
115
lp:bzr-colocated plugin
116
117
Further integration
118
-------------------
119
120
Loggerhead and Launchpad need to be updated to show colocated branches
121
(perhaps in a similar way as they would show tags?).
122
123
qbzr/bzr-gtk need to be updated to support colocated branches.
Loggerhead is a web-based interface for Breezy
Version: 2.0.1