/brz/remove-bazaar

To get this branch, use:
bzr branch http://gegoxaren.bato24.eu/bzr/brz/remove-bazaar

« back to all changes in this revision

Viewing changes to doc/developers/tortoise-strategy.txt

  • Committer: Mark Hammond
  • Date: 2008-04-09 08:19:38 UTC
  • mto: This revision was merged to the branch mainline in revision 3366.
  • Revision ID: mhammond@skippinet.com.au-20080409081938-pgbl7xc4jb1lt3fq
based on the suggestions of a few people, make the tone of the document
more authoritative, documenting decisions made rather than the options
available.

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/developers/tortoise-strategy.txt
6
6
Introduction
7
7
------------
8
8
 
9
 
This document outlines the options available for Bazaar to integrate with the
10
 
Windows Shell. It first describes the general architecture of Windows Shell
11
 
Extensions, then looks at the C++ implemented TortoiseSvn and the Python
12
 
implemented TortoiseBzr, and concludes with a number of concrete proposals
13
 
for moving TortoiseBzr forward.
 
9
This document details the imlpementation strategy chosen for the
 
10
Bazaar Windows Shell Extensions, otherwise known as TortoiseBzr, or TBZR.
 
11
As justification for the strategy, it also describes the general architecture
 
12
of Windows Shell Extensions, then looks at the C++ implemented TortoiseSvn
 
13
and the Python implemented TortoiseBzr, and discusses alternative
 
14
implementation strategies, and the reasons they were not chosen.
 
15
 
 
16
The following points summarize the  strategy.
 
17
 
 
18
* Main shell extension code will be implemented in C++, and be as thin as
 
19
  possible.  It will not directly do any VCS work, but instead will perform
 
20
  all operations via either external applications or an RPC server.
 
21
 
 
22
* Most VCS operations will be performed by external applications.  For
 
23
  example, committing changes or viewing history will spawn a child
 
24
  process that provides its own UI.
 
25
 
 
26
* For operations where spawning a child process is not practical, an
 
27
  external RPC server will be implemented in Python and will directly use
 
28
  the VCS library. In the short term, there will be no attempt to create a
 
29
  general purpose RPC mechanism, but instead will be focused on keeping the
 
30
  C++ RPC client as thin, fast and dumb as possible.
 
31
 
 
32
Background Information
 
33
----------------------
14
34
 
15
35
The facts about shell extensions
16
 
----------------------------------
 
36
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
17
37
 
18
38
Well - the facts as I understand them :)
19
39
 
69
89
[1]: http://blogs.msdn.com/oldnewthing/archive/2006/12/18/1317290.aspx
70
90
 
71
91
Analysis of TortoiseSVN code
72
 
-----------------------------
 
92
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
73
93
 
74
94
TortoiseSVN is implemented in C++. It relies on an external process to
75
95
perform most UI (such as diff, log, commit etc commands), but it appears to
102
122
the external application, which might offer better facilities.
103
123
 
104
124
Analysis of existing TortoiseBzr code
105
 
--------------------------------------
 
125
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
106
126
 
107
127
The existing code is actually quite cool given its history (SoC student,
108
128
etc), so this should not be taken as criticism of the implementer nor of the
161
181
Trivially, the code is not PEP8 compliant and was written by someone fairly
162
182
inexperienced with the language.
163
183
 
164
 
Conclusions
165
 
------------
166
 
 
167
 
A strategic decision needs to be made about the use of Python in the shell
168
 
extension itself. The use of Python means that there is a larger chance of
169
 
conflicting with existing applications, or even existing Python implemented
170
 
shell extensions. It will also increase the memory usage of all applications
171
 
which use the shell. While this may create problems for a small number of
172
 
users, it may create a wider perception of instability or resource hogging.
173
 
 
174
 
There are 2 credible options:
175
 
 
176
 
Stick to Python
177
 
~~~~~~~~~~~~~~~~~
178
 
 
179
 
This is the simplest to implement but has all the limitations above. We just
180
 
continue to develop the existing code and commit to this model for the
181
 
foreseeable future.
182
 
 
183
 
We probably need something similar to TSVNCache.exe - an external process
184
 
used to share state between processes - and this too could be implemented in
185
 
Python.
186
 
 
187
 
Hybrid Python and C++ implementation
188
 
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
189
 
 
190
 
In this model, we would still use something like TSVNCache.exe (this external
 
184
Detailed Implementation Strategy
 
185
---------------------------------
 
186
 
 
187
We will create a hybrid Python and C++ implementation.  In this model, we
 
188
would still use something like TSVNCache.exe (this external
191
189
process doesn't have the same restrictions as the shell extension itself) but
192
190
go one step further - use this remote process for *all* interactions with
193
191
bzr, including status and other "must be fast" operations. This would allow
194
192
the shell extension itself to be implemented in C++, but still take advantage
195
 
of Python for much of the logic. If we resisted the temptation to abstract
196
 
the Windows shell requirements into a more general purpose mechanism, the
197
 
shell could remain thin and not too painful to implement in C++ - it becomes
198
 
an RPC-stub to the Python implemented process.
 
193
of Python for much of the logic.
199
194
 
200
 
One possible implementation strategy could be to work towards the above
201
 
infrastructure (ie, a single process doing all VCS work), while keeping the
202
 
shell extension implemented in Python - but without using bzrlib. This would
203
 
allow us to focus on this shared-cache/remote-process infrastructure without
204
 
immediately re-implementing a shell extension in C++. Longer term, once the
 
195
A pragmatic implementation strategy will be used to work towards the above
 
196
infrastructure - we will keep the shell extension implemented in Python - but
 
197
without using bzrlib. This would allow us to focus on this
 
198
shared-cache/remote-process infrastructure without immediately
 
199
re-implementing a shell extension in C++. Longer term, once the
205
200
infrastructure is in place and as optimized as possible, we can move to C++
206
201
code in the shell calling our remote Python process. This port should try and
207
202
share as much code as possible from TortoiseSvn, including overlay handlers.
219
214
important. Either way, this can change independently from the shell
220
215
extension.
221
216
 
222
 
 
223
217
Performance considerations
224
 
----------------------------
225
 
 
226
 
The following discussions assume the "Hybrid Python and C++ implementation"
227
 
strategy, discussed above, is chosen for implementation. To recap, TBZR
228
 
becomes a C++ implemented DLL using RPC to talk to a Python implemented
229
 
"server" which does all BZR work.
 
218
~~~~~~~~~~~~~~~~~~~~~~~~~~~
230
219
 
231
220
As discussed above, the model used by Tortoise is that most "interesting"
232
221
things are done by external applications. Most Tortoise implementations
270
259
people, for example.
271
260
 
272
261
RPC options
273
 
-------------
 
262
~~~~~~~~~~~~
274
263
 
275
264
Due to the high number of calls for icon overlays, the RPC overhead must be
276
265
kept as low as possible. Due to the client side being implemented in C++,
293
282
appear sufficient to implement a prototype.
294
283
 
295
284
Vista versus XP
296
 
------------------
 
285
~~~~~~~~~~~~~~~~
297
286
 
298
287
Let's try and avoid an OS advocacy debate :) But it is probably true that
299
288
TBZR will, over its life, be used by more Vista computers than XP ones. In
313
302
Implementation plan:
314
303
--------------------
315
304
 
 
305
The following is a high-level set of milestones for the implementation:
 
306
 
316
307
* Design the RPC mechanism used for icon overlays (ie, binary format used for
317
308
  communication)
318
309
 
338
329
  necessary.
339
330
 
340
331
* Create binary for alpha releases, then go round-and-round until its baked.
 
332
 
 
333
Alternative Implementation Strategies
 
334
-------------------------------------
 
335
 
 
336
Only one credible alternative strategy was identified, as discussed below. No
 
337
languages other than Python and C++ were considered; Python as the bzr
 
338
library and existing extensions are written in Python and otherwise only C++
 
339
for reasons outlined in the background on shell extensions above.
 
340
 
 
341
Implement Completely in Python
 
342
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
343
 
 
344
This would keep the basic structure of the existing TBZR code, with the
 
345
shell extension continuing to pull in Python and all libraries used by Bzr
 
346
into various processes.
 
347
 
 
348
Although implementation simplicity is a key benefit to this option, it was
 
349
not chosen for various reasons; The use of Python means that there is a
 
350
larger chance of conflicting with existing applications, or even existing
 
351
Python implemented shell extensions. It will also increase the memory usage
 
352
of all applications which use the shell. While this may create problems for a
 
353
small number of users, it may create a wider perception of instability or
 
354
resource hogging.