~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to doc/en/user-guide/introducing_bazaar.txt

  • Committer: Canonical.com Patch Queue Manager
  • Date: 2007-11-30 05:43:20 UTC
  • mfrom: (3054.1.1 ianc-integration)
  • Revision ID: pqm@pqm.ubuntu.com-20071130054320-b4oer0rcbiy2ouzg
Bazaar User Guide for 1.0rc (Ian Clatworthy)

Show diffs side-by-side

added added

removed removed

Lines of Context:
 
1
Introducing Bazaar
 
2
==================
 
3
 
 
4
What is Bazaar?
 
5
---------------
 
6
 
 
7
Bazaar is a tool for helping people collaborate. It does this by
 
8
tracking how a group of files evolves and using that information to help
 
9
people merge their changes together as safely as possible.
 
10
 
 
11
In general, tools that do this are known as revision control systems or
 
12
version control systems (VCS). In the past, VCS tools have been popular
 
13
with software developers. In the future, VCS tools will undoubtedly also be
 
14
important for other groups of people looking to work together on
 
15
files and documents, e.g. technical writers and translators.
 
16
 
 
17
A brief history of version control systems
 
18
------------------------------------------
 
19
 
 
20
VCS tools have been evolving for several decades now. In simple terms,
 
21
there have been 5 generations of tools:
 
22
 
 
23
 1. file versioning tools, e.g. SCCS, VCS
 
24
 2. tree versioning tools - central style, e.g. CVS
 
25
 3. tree versioning tools - central style, done right, e.g. Subversion
 
26
 4. tree versioning tools - distributed style, e.g. Arch
 
27
 5. tree versioning tools - distributed style, done right, e.g. Bazaar.
 
28
 
 
29
The design and implementation of Bazaar builds on the lessons learned
 
30
from all the previous generations of tools. In particular, Bazaar
 
31
cleanly supports both the central and the distributed version
 
32
control models so you can change models as it makes sense, without
 
33
needing to change tools.
 
34
 
 
35
Central vs distributed VCS
 
36
--------------------------
 
37
 
 
38
Many traditional VCS tools require a central server which provides the
 
39
change history or *repository* for a tree of files. To work on the files,
 
40
users need to connect to the server and *checkout* the files. This gives
 
41
them a directory or *working tree* in which a person can make changes.
 
42
To record or *commit* these changes, the user needs access to the central
 
43
server and they need to unsure they have merged their work with the latest
 
44
version stored before trying to commit. This approach is known as the
 
45
centralized model. 
 
46
 
 
47
The centralized model has proven useful over time but it can have some notable
 
48
drawbacks. Firstly, a centralized VCS requires that one is able to connect
 
49
to the server whenever one wants to do version control work. Secondly, the
 
50
centralized model tightly links the act of **snapshotting** changes with the act
 
51
of **publishing** those changes. This can be good in some circumstances but
 
52
it has a negative influence on quality in others.
 
53
 
 
54
Distributed VCS tools let users and teams have multiple repositories
 
55
rather than just a single central one. In Bazaar's case, the history is
 
56
normally kept in the same place as the code that is being version controlled.
 
57
This allows the user to commit their changes whenever it makes sense, even
 
58
when offline. Network access is only required when publishing changes or
 
59
when accessing changes in another location.
 
60
 
 
61
In fact, using distributed VCS tools wisely can have advantages well
 
62
beyond the obvious one of disconnected operations for developers.
 
63
Other advantages include:
 
64
 
 
65
 * easier for developers to create experimental branches
 
66
 * easier ad-hoc collaboration with peers
 
67
 * less time required on mechanical tasks - more time for creativity
 
68
 
 
69
 * increased release management flexibility through the use of
 
70
   "feature-wide" commits
 
71
 
 
72
 * trunk quality and stability can be kept higher, making everyone's
 
73
   job less stressful
 
74
 
 
75
 * in open source communities:
 
76
 
 
77
   * easier for non-core developers to create and maintain changes
 
78
 
 
79
   * easier for core developers to work with non-core developers and
 
80
     move them into the core
 
81
 
 
82
 * in companies, easier to work with distributed and outsourced teams.
 
83
   
 
84
For a detailed look at the advantages of distributed VCS tools over
 
85
centralized VCS tools, see http://bazaar-vcs.org/BzrWhy.
 
86
 
 
87
 
 
88
Key features of Bazaar
 
89
----------------------
 
90
 
 
91
While Bazaar is not the only distributed VCS tool around, it does have some
 
92
notable features that make it an excellent choice for many teams and
 
93
communities. These include:
 
94
 
 
95
 * it **Just Works** - a high focus on usability and performance
 
96
 * **adaptive** - cleanly supports many different ways of working together
 
97
 * **rich metadata** that tracks merge history across distributed locations,
 
98
   understands directories as first-class objects and correctly tracks
 
99
   renames of both files and directories
 
100
 * **integrated merging** that uses this metadata intelligently to
 
101
   ensure that merging is safe without being painful, letting you
 
102
   collaborate without fear
 
103
 * **truly portable** across many operating systems including Windows
 
104
 * **safe with your data** - integrity is checked using cryptographic
 
105
   techniques and all changes can be digitally signed if required
 
106
 * **low administration**, e.g. access to FTP or SFTP is enough to
 
107
   share with others - no special server required
 
108
 * **efficiently stores data** across branches in a flexible and safe way
 
109
 * an **open architecture and API** that makes it easy to integrate
 
110
   with other tools
 
111
 * a **large number of plugins** including bzr-svn and GUI front-ends
 
112
 * **excellent integration** with a range of companion tools and services
 
113
   including PQM, Bundle Buggy and Launchpad
 
114
 * **completely open source**
 
115
 * **commercial training and support** available from Canonical,
 
116
   the company that sponsors Ubuntu.
 
117
 
 
118
While all of these are important, perhaps the greatest asset Bazaar has is
 
119
an active and growing open source community behind it. Bazaar is completely
 
120
free software written in Python so it is easy to contribute improvements.
 
121
Our collective goal is to build and support a distributed VCS tool that
 
122
developers love to use, a tool that helps them get their job done without
 
123
getting in their way. If you wish to get involved, please see
 
124
http://bazaar-vcs.org/Community.
 
125
 
 
126
 
 
127
Learning more
 
128
-------------
 
129
 
 
130
This manual provides an easy to read introduction to Bazaar and how to use
 
131
it effectively.  It is recommended that all users read at least the rest of
 
132
this chapter as it:
 
133
 
 
134
 * explains the core concepts users need to know
 
135
 * introduces some popular ways of using Bazaar to collaborate.
 
136
 
 
137
Chapters 2-6 provide a closer look at how to use Bazaar to complete
 
138
various tasks. It is recommended that most users read these in first-to-last
 
139
order shortly after starting to use Bazaar. Chapters 7 and beyond provide
 
140
additional information including some recommended best practices.
 
141
This material can be read when required and in any order.
 
142
 
 
143
If you are already familar with other version control tools,
 
144
you may wish to get started quickly by reading the following documents:
 
145
 
 
146
 * `Bazaar in five minutes`_ - a mini-tutorial
 
147
 
 
148
 * `Bazaar Quick Start Guide`_ - a one page summary of commonly used commands.
 
149
 
 
150
The online help and `Bazaar User Reference`_ are also particularly useful as
 
151
they provide all the gory details on the commands and options available.
 
152
 
 
153
.. _Bazaar in five minutes: ../mini-tutorial/index.html
 
154
.. _Bazaar Quick Start Guide: ../quick-reference/quick-start-summary.svg
 
155
.. _Bazaar User Reference: ../user-reference/bzr_man.html
 
156
 
 
157
We hope you find this manual useful. If you have suggestions on how it
 
158
or the rest of Bazaar's documentation can be improved, please contact
 
159
us on the mailing list, bazaar@lists.canonical.com.