~bzr-pqm/bzr/bzr.dev

2977.1.2 by Ian Clatworthy
add conflict handling as an Appendix + minor tweaks
1
Workflows
2
=========
2977.1.1 by Ian Clatworthy
First cut at new look User Guide including chapters 1 and 2
3
4
Bazaar is just a tool
5
---------------------
6
3309.1.1 by Ian Clatworthy
Reduce evangelism in the User Guide
7
Bazaar supports many different ways of working together.
8
This means that you can
2977.1.1 by Ian Clatworthy
First cut at new look User Guide including chapters 1 and 2
9
start with one workflow and adapt it over time as circumstances
10
change. There is no "one true way" that always makes sense and
2977.1.17 by Ian Clatworthy
more chapter 1 tweaks
11
there never will be. This section provides a brief overview of
2977.1.1 by Ian Clatworthy
First cut at new look User Guide including chapters 1 and 2
12
some popular workflows supported by Bazaar.
13
3309.1.1 by Ian Clatworthy
Reduce evangelism in the User Guide
14
Keep in mind that these workflow are just *some* examples of how
15
Bazaar can be used. You may want to use a workflow not listed here,
16
perhaps building on the ideas below.
2977.1.1 by Ian Clatworthy
First cut at new look User Guide including chapters 1 and 2
17
18
Solo
19
----
20
3237.1.2 by John Arbash Meinel
wrap doc/en/user-guide/bazaar_workflows.txt for 79 characters
21
Whether developing software, editing documents or changing configuration files,
22
having an easy-to-use VCS tool can help. A single user can use this workflow
23
effectively for managing projects where they are the only contributor.
2977.1.1 by Ian Clatworthy
First cut at new look User Guide including chapters 1 and 2
24
25
.. image:: images/workflows_single.png
26
2977.1.17 by Ian Clatworthy
more chapter 1 tweaks
27
Advantages of this workflow over not using version control at all include:
2977.1.1 by Ian Clatworthy
First cut at new look User Guide including chapters 1 and 2
28
29
 * backup of old versions
30
 * rollback to an earlier state
31
 * tracking of history.
32
3237.1.2 by John Arbash Meinel
wrap doc/en/user-guide/bazaar_workflows.txt for 79 characters
33
The key features of Bazaar appropriate for this workflow are low administration
34
(no server setup) and ease of use.
2977.1.1 by Ian Clatworthy
First cut at new look User Guide including chapters 1 and 2
35
36
37
Partner
38
-------
39
3237.1.2 by John Arbash Meinel
wrap doc/en/user-guide/bazaar_workflows.txt for 79 characters
40
Sometimes two people need to work together sharing changes as they go. This
41
commonly starts off as a *Solo* workflow (see above) or a team-oriented
42
workflow (see below). At some point, the second person takes a branch (copy
43
including history) of what the first person has done. They can then work in
44
parallel exchanging changes by merging when appropriate.
2977.1.1 by Ian Clatworthy
First cut at new look User Guide including chapters 1 and 2
45
46
.. image:: images/workflows_peer.png
47
48
Advantages over *Solo* are:
49
50
 * easier sharing of changes
3237.1.2 by John Arbash Meinel
wrap doc/en/user-guide/bazaar_workflows.txt for 79 characters
51
 * each line of each text file can be attributed to a particular change
52
   including who changed it, when and why.
2977.1.1 by Ian Clatworthy
First cut at new look User Guide including chapters 1 and 2
53
54
When implementing this workflow, Bazaar's advantages over CVS and Subversion include:
55
56
 * no server to setup
57
 * intelligent merging means merging multiple times isn't painful.
58
59
60
Centralized
61
-----------
62
3237.1.2 by John Arbash Meinel
wrap doc/en/user-guide/bazaar_workflows.txt for 79 characters
63
Also known as *lock-step*, this is essentially the same as the workflow
64
encouraged/enforced by CVS and Subversion. All developers work on the same
65
branch (or branches). They run ``bzr update`` to get their checkout up-to-date,
66
then ``bzr commit`` to publish their changes to the central location.
2977.1.1 by Ian Clatworthy
First cut at new look User Guide including chapters 1 and 2
67
68
.. image:: images/workflows_centralized.png
69
3237.1.2 by John Arbash Meinel
wrap doc/en/user-guide/bazaar_workflows.txt for 79 characters
70
Subversion and CVS are good choices for implementing this workflow because they
3309.1.1 by Ian Clatworthy
Reduce evangelism in the User Guide
71
make it easy. Bazaar directly supports it as well while providing some
3237.1.2 by John Arbash Meinel
wrap doc/en/user-guide/bazaar_workflows.txt for 79 characters
72
important advantages over CVS and Subversion:
2977.1.1 by Ian Clatworthy
First cut at new look User Guide including chapters 1 and 2
73
2977.1.17 by Ian Clatworthy
more chapter 1 tweaks
74
 * better branching and merging
2977.1.1 by Ian Clatworthy
First cut at new look User Guide including chapters 1 and 2
75
 * better renaming support.
76
77
78
Centralized with local commits
79
------------------------------
80
3237.1.2 by John Arbash Meinel
wrap doc/en/user-guide/bazaar_workflows.txt for 79 characters
81
This is essentially the same as the *Centralized* model, except that when
82
developers are making a series of changes, they do ``commit --local`` or unbind
83
their checkout. When it is complete, they commit their work to the shared
84
mainline.
2977.1.1 by Ian Clatworthy
First cut at new look User Guide including chapters 1 and 2
85
86
.. image:: images/workflows_localcommit.png
87
88
Advantages over *Centralized*:
89
90
 * Can work offline, e.g. when disconnected during travel
91
 * Less chance for a bad commit to interfere with everyone else's work
92
3237.1.2 by John Arbash Meinel
wrap doc/en/user-guide/bazaar_workflows.txt for 79 characters
93
Subversion and CVS do not support this model. Other distributed VCS tools can
94
support it but do so less directly than Bazaar does.
2977.1.1 by Ian Clatworthy
First cut at new look User Guide including chapters 1 and 2
95
96
97
Decentralized with shared mainline
98
----------------------------------
99
3237.1.2 by John Arbash Meinel
wrap doc/en/user-guide/bazaar_workflows.txt for 79 characters
100
In this workflow, each developer has their own branch or branches, plus commit
101
rights to the main branch. They do their work in their personal branch, then
102
merge it into the mainline when it is ready.
2977.1.1 by Ian Clatworthy
First cut at new look User Guide including chapters 1 and 2
103
104
.. image:: images/workflows_shared.png
105
106
Advantage over *Centralized with local commits*:
107
108
 * Easier organization of work - separate changes can be developed in their own branches
2977.1.17 by Ian Clatworthy
more chapter 1 tweaks
109
 * Developers can merge one another's personal branches when working on something together.
2977.1.1 by Ian Clatworthy
First cut at new look User Guide including chapters 1 and 2
110
2977.1.17 by Ian Clatworthy
more chapter 1 tweaks
111
Subversion and CVS do not support this model. Other distributed VCS
112
tools support it. Many features of Bazaar are good for this workflow
113
including ease of use, shared repositories, integrated merging and
114
rich metadata (including directory rename tracking).
2977.1.1 by Ian Clatworthy
First cut at new look User Guide including chapters 1 and 2
115
116
117
Decentralized with human gatekeeper
118
-----------------------------------
119
3237.1.2 by John Arbash Meinel
wrap doc/en/user-guide/bazaar_workflows.txt for 79 characters
120
In this workflow, each developer has their own branch or branches, plus
121
read-only access to the main branch. One developer (the gatekeeper) has commit
122
rights to the main branch. When a developer wants their work merged, they ask
123
the gatekeeper to merge it. The gatekeeper does code review, and merges the
124
work into the main branch if it meets the necessary standards.
2977.1.1 by Ian Clatworthy
First cut at new look User Guide including chapters 1 and 2
125
126
.. image:: images/workflows_gatekeeper.png
127
128
Advantage over *Decentralized with shared mainline*:
129
2977.1.17 by Ian Clatworthy
more chapter 1 tweaks
130
 * Code is always reviewed before it enters the mainline
131
 * Tighter control over when changes get incorporated into the mainline.
2977.1.1 by Ian Clatworthy
First cut at new look User Guide including chapters 1 and 2
132
3237.1.2 by John Arbash Meinel
wrap doc/en/user-guide/bazaar_workflows.txt for 79 characters
133
A companion tool of Bazaar's called Bundle Buggy can be very useful for
134
tracking what changes are up for review, their status and reviewer comments.
2977.1.1 by Ian Clatworthy
First cut at new look User Guide including chapters 1 and 2
135
136
137
Decentralized with automatic gatekeeper
138
---------------------------------------
139
3237.1.2 by John Arbash Meinel
wrap doc/en/user-guide/bazaar_workflows.txt for 79 characters
140
In this workflow, each developer has their own branch or branches, plus
141
read-only access to the mainline. A software gatekeeper has commit rights to
142
the main branch. When a developer wants their work merged, they request another
143
person to review it. Once it has passed review, either the original author or
144
the reviewer asks the gatekeeper software to merge it, depending on team
145
policies. The gatekeeper software does a merge, a compile, and runs the test
146
suite. If and only if the code passes, it is merged into the mainline.
2977.1.1 by Ian Clatworthy
First cut at new look User Guide including chapters 1 and 2
147
3237.1.2 by John Arbash Meinel
wrap doc/en/user-guide/bazaar_workflows.txt for 79 characters
148
Note: As an alternative, the review step can be skipped and the author can
149
submit the change to the automatic gatekeeper without it. (This is particularly
150
appropriate when using practices such as Pair Programming that effectively
151
promote just-in-time reviews instead of reviewing code as a separate step.)
2977.1.1 by Ian Clatworthy
First cut at new look User Guide including chapters 1 and 2
152
153
.. image:: images/workflows_pqm.png
154
155
Advantages over *Decentralized with human gatekeeper*:
156
3237.1.2 by John Arbash Meinel
wrap doc/en/user-guide/bazaar_workflows.txt for 79 characters
157
 * Code is always tested before it enters the mainline (so the integrity of the
158
   mainline is higher)
2977.1.1 by Ian Clatworthy
First cut at new look User Guide including chapters 1 and 2
159
 * Scales better as teams grow.
160
3237.1.2 by John Arbash Meinel
wrap doc/en/user-guide/bazaar_workflows.txt for 79 characters
161
A companion tool of Bazaar's called Patch Queue Manager (PQM) can provide the
162
automated gatekeeper capability.
2977.1.1 by Ian Clatworthy
First cut at new look User Guide including chapters 1 and 2
163
164
165
Implementing a workflow
166
-----------------------
167
2977.1.17 by Ian Clatworthy
more chapter 1 tweaks
168
For an in-depth look at how to implement each of the workflows above,
169
see chapters 3 to 6 in this manual. First though, chapter 2
2977.1.1 by Ian Clatworthy
First cut at new look User Guide including chapters 1 and 2
170
explains some important pre-requisites including installation, general
171
usage instructions and configuration tips.