/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/overview.txt

  • Committer: Martin Pool
  • Date: 2008-09-04 04:55:36 UTC
  • mto: This revision was merged to the branch mainline in revision 3691.
  • Revision ID: mbp@sourcefrog.net-20080904045536-p7royuwgrixs8q4b
Improved review process docs and separate out architectural overview

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/developers/overview.txt
 
1
=============================
 
2
Bazaar Architectural Overview
 
3
=============================
 
4
 
 
5
This document describes the key classes and concepts within Bazaar.  It is
 
6
intended to be useful to be useful to people working on the Bazaar
 
7
codebase, or to people writing plugins.
 
8
 
 
9
If you have any questions or something seems to be incorrect, unclear or
 
10
missing, please talk to us in ``irc://irc.freenode.net/#bzr``, or write to
 
11
the Bazaar mailing list.  To propose a correction or addition to this
 
12
document, send a merge request or new text to the mailing list.
 
13
 
 
14
The current version of this document is available in the file
 
15
``doc/developers/overview.txt`` in the source tree, and from 
 
16
<http://doc.bazaar-vcs.org/bzr.dev/>.
 
17
 
 
18
See also:
 
19
 
 
20
 * `Bazaar Developer Documentation Catalog <../../developers/index.html>`_.
 
21
 * `Bazaar Developer Guide <../../en/developer-guide/HACKING.html>`_
 
22
   (particularly the *Coding Style Guidelines* section.)
 
23
 
 
24
.. contents::
 
25
 
 
26
Essential Domain Classes
 
27
########################
 
28
 
 
29
The core domain objects within the bazaar model are:
 
30
 
 
31
* Transport
 
32
 
 
33
* Branch
 
34
 
 
35
* Repository
 
36
 
 
37
* WorkingTree
 
38
 
 
39
Transports are explained below. See http://bazaar-vcs.org/Classes/
 
40
for an introduction to the other key classes.
 
41
 
 
42
Transport
 
43
#########
 
44
 
 
45
The ``Transport`` layer handles access to local or remote directories.
 
46
Each Transport object acts like a logical connection to a particular
 
47
directory, and it allows various operations on files within it.  You can
 
48
*clone* a transport to get a new Transport connected to a subdirectory or
 
49
parent directory.
 
50
 
 
51
Transports are not used for access to the working tree.  At present
 
52
working trees are always local and they are accessed through the regular
 
53
Python file io mechanisms.
 
54
 
 
55
Filenames vs URLs
 
56
=================
 
57
 
 
58
Transports work in URLs.  Take note that URLs are by definition only
 
59
ASCII - the decision of how to encode a Unicode string into a URL must be
 
60
taken at a higher level, typically in the Store.  (Note that Stores also
 
61
escape filenames which cannot be safely stored on all filesystems, but
 
62
this is a different level.)
 
63
 
 
64
The main reason for this is that it's not possible to safely roundtrip a
 
65
URL into Unicode and then back into the same URL.  The URL standard
 
66
gives a way to represent non-ASCII bytes in ASCII (as %-escapes), but
 
67
doesn't say how those bytes represent non-ASCII characters.  (They're not
 
68
guaranteed to be UTF-8 -- that is common but doesn't happen everywhere.)
 
69
 
 
70
For example if the user enters the url ``http://example/%e0`` there's no
 
71
way to tell whether that character represents "latin small letter a with
 
72
grave" in iso-8859-1, or "latin small letter r with acute" in iso-8859-2
 
73
or malformed UTF-8.  So we can't convert their URL to Unicode reliably.
 
74
 
 
75
Equally problematic if we're given a url-like string containing non-ascii
 
76
characters (such as the accented a) we can't be sure how to convert that
 
77
to the correct URL, because we don't know what encoding the server expects
 
78
for those characters.  (Although this is not totally reliable we might still
 
79
accept these and assume they should be put into UTF-8.)
 
80
 
 
81
A similar edge case is that the url ``http://foo/sweet%2Fsour`` contains
 
82
one directory component whose name is "sweet/sour".  The escaped slash is
 
83
not a directory separator.  If we try to convert URLs to regular Unicode
 
84
paths this information will be lost.
 
85
 
 
86
This implies that Transports must natively deal with URLs; for simplicity
 
87
they *only* deal with URLs and conversion of other strings to URLs is done
 
88
elsewhere.  Information they return, such as from ``list_dir``, is also in
 
89
the form of URL components.
 
90
 
 
91
 
 
92
Repository
 
93
##########
 
94
 
 
95
Repositories store committed history: file texts, revisions, inventories,
 
96
and graph relationships between them.
 
97
 
 
98
 
 
99
 
 
100
..
 
101
   vim: ft=rst tw=74 ai