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. |