← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to doc/en/admin-guide/upgrade.txt

(jameinel) Allow 'bzr serve' to interpret SIGHUP as a graceful shutdown.
 (bug #795025) (John A Meinel)

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/en/admin-guide/upgrade.txt
 
1
Upgrades
 
2
========
 
3
 
 
4
Bazaar has a strong commitment to inter-version compatibility both on disk and
 
5
over the network.  Newer clients should be able to interact with older
 
6
versions on the server (although perhaps not at optimal speed) and older
 
7
clients should also be able to communicate with newer versions of Bazaar on
 
8
the server.  Divergences from this rule are considered bugs and are fixed in
 
9
later versions.
 
10
 
 
11
That said, Bazaar is constantly improving and the most recent versions are the
 
12
most featureful and have better performance.  In particular, the Bazaar
 
13
versions 2.0 and later have significant advantages over earlier versions,
 
14
including a more compact disk format, faster network operations and overall
 
15
performance improvements.  With the 2.0 release, Bazaar has moved to a
 
16
stable/development release model where the 2.x series is maintained with
 
17
bugfixes releases for six months, while simultaneously the 2.(x+1) series is
 
18
being developed with monthly beta releases that are suitable for everyday use.
 
19
Bazaar development has a stable trunk with an extensive test suite, so there
 
20
is no reason to fear using the development series for everyday use, it simply
 
21
changes more often than the stable series.  Many users do run the development
 
22
version of Bazaar and update it regularly, including most of the Bazaar
 
23
developers themselves.
 
24
 
 
25
 
 
26
Software upgrades
 
27
-----------------
 
28
 
 
29
Upgrading the Bazaar software is as simple as re-installing the Python package
 
30
using either the latest binary package for Windows or Mac OS X, the binary
 
31
package provided by your GNU/Linux distribution, or installing from the source
 
32
release.  See http://wiki.bazaar.canonical.com/Downloads for the latest
 
33
releases for all supported platforms.
 
34
 
 
35
Bazaar's later versions support all of the earlier disk formats (back to the
 
36
very first one), so there is no need to upgrade the branches on the disk when
 
37
upgrading the software.  To make use of particular new features that might
 
38
need updated versions on both the server and developer's machines, it does not
 
39
matter if the clients or the servers are upgraded first.
 
40
 
 
41
 
 
42
Disk format upgrades
 
43
--------------------
 
44
 
 
45
In its evolution, Bazaar has used a sequence of disk formats for improved
 
46
storage efficiency and speed.  With the new disk format released in version
 
47
2.0, there is a commitment to keep that disk format until version 3.0 is
 
48
released, which has not even been planned yet.  (Bazaar 2.0 was released
 
49
almost two years after Bazaar 1.0.)  As a result, disk format upgrades should
 
50
be extremely infrequent.
 
51
 
 
52
If there are existing branches in an older format that you would like to
 
53
upgrade to the latest format, you can see the `2.0 Upgrade Guide
 
54
<../upgrade-guide/index.html>`_ for more information.  From the system
 
55
administration perspective, it is important to coordinate the timing of
 
56
various upgrades in the process.  First, the central branches on the server
 
57
should be upgraded.  Next, any local mirrors that developers have should be
 
58
upgraded.  Finally, developers' local branches should be upgraded.  These
 
59
upgrades will require an appropriate version of the software whenever they are
 
60
performed.  (It is possible to upgrade branches remotely over the network, but
 
61
it may be much slower.)
 
62
 
 
63
 
 
64
Plugin upgrades
 
65
---------------
 
66
 
 
67
When Bazaar does update its version, plugins that use the Bazaar API may need
 
68
to be upgraded to reflect changes in that API.  Some plugins have strict
 
69
version dependencies on the version of the Bazaar API that they will accept.
 
70
If this is the case, then you should ensure that the plugins you depend on
 
71
have been updated *before* you upgrade your Bazaar version to avoid a
 
72
situation where your plugins won't work with the installed version of Bazaar.
 
73
If this does happen, then the solution is simply to reinstall the previous
 
74
version of Bazaar that *did* work with the plugins.  For installations that
 
75
depend on a large number of plugins, this sort of version upgrade should be
 
76
tested in a safe sandbox to ensure that the entire collection of Bazaar and
 
77
its plugins can all work together.