This tutorial is for people that are experienced with SVN. Its generally better to start off with the normal tutorials if you do not have experience with SVN.
This tutorial is broken up into two sections; concepts and behaviour. The concept section is concerned with giving you the understanding to run Bazaar effectively. The second section eschews all of the details about what and why things are and jumps straight into the usage of Bazaar.
If you learn better with a hands on approach, then skip straight ahead to section 2. If, on the other hand, you are the sort of person that likes to think a bit about things before you do them, then section 1 is for you.
You may also want to look at Tutorials/CentralizedWorkflow for information on using bzr in a centralized fashion.'
Section 1 - Explanation of Bazaar
What's that hype about?
So, by this point you've probably gotten it from all sides about how you need to give decentralized revision control systems a try, like, "Bazaar does this! It does that too! It can merge this, allows for independent development, and generally makes hacking fun again". For all the hype that you hear, Bazaar probably finds lost socks as well.
So can it really do all of these things? Nope. It's a lie. Bazaar will not find the sock that slipped behind your washing machine. The rest of it is true beyond a doubt.
What is DRCS all about?
Project management used to be highly centralized. People working together on a project would meet together in one place, work together on a project and release their work. If you didn't work in the same place, you were an outsider that at best could send in patches.
To say that the world has changed since the internet became ubiquitous is an understatement. Developers for free software projects are spread throughout the world. Wouldn't it make sense if our development tools worked the same way that we do?
How is a branch different from a SVN repository?
The purpose of decentralized revision control systems is to break the chain between the developer and the server. This is done by moving the RCS data from the central server down to the developer. This is done by making a Bzr branch something that is like both a repository and a working tree.
Logically combining the RCS data with the working tree means that when you branch from somebody else, you end up with a repository of your own. That means you can commit in your branch without needing to ask for permission from the person you branched from. It's almost as if you copied their SVN repository and made a SVN repository of your own.
How do repositories fit into the Bazaar model?
The catch to keeping RCS data and working trees logically related is that each time you make a branch, you copy a lot of RCS data. Some revision control systems, such as Bazaar, allow one to create a shared repository. A shared respository allows the user to store the RCS data for several branches in one place. That way, the RCS data common to several branches is only represented once on the filesystem.
How does merging work between branches?
Section 2 - Common SVN behaviours translated into Bazaar
This section explains how to perform common SVN behaviours in a Bazaar world. Unfortunately, this means that I won't be able to teach you many of the things that are unique to decentralized revision control systems.
This section covers how to use Bazaar in checkout mode. Reading section 3, which covers standard Bazaar methods, is highly encouraged.
Getting a checkout
In the SVN world, somebody has already setup a SVN repository and has told you a URL to "checkout". You checkout with:
$ svn checkout URL
- Usually the URL is a svn:// url, like the below example:
$ svn checkout svn://somemachine.com/this/directory/here
However, in the Bazaar world, this is usually done with:
$ bzr checkout http://somemachine.com/this/directory/here
Updating a checkout
In the SVN world you may have done a checkout. From time to time you have to get new changes from the repository and apply them to your checkout. This usually looks something like this:
$ cd codebase/ $ svn update
This looks very similiar in the Bazaar world:
$ cd codebase/ $ bzr update
In both the SVN and Bazaar cases this will mean that the changes in the repository or branch that you do not yet have in the working tree will be applied. You might have to deal with conflicts.
Seeing how a working tree has changed since the last commit
In the SVN world we often want to check how we have changed things since we last committed. By checking how the code base has changed, we can see what we're about to commit before we actually perform the commit.
In the SVN world, we would check the changes this way:
$ svn status [see a list of files that have changed] $ svn status -u [see a list of new revisions in the repository] $ svn diff [see a diff of how files have changed]
This is very similar in Bazaar:
$ bzr status [see a list of files that have changed] $ bzr missing [see a list of new revisions in the parent branch] $ bzr diff [see a diff of how files have changed]
The diff action in both systems will result in a diff that you can review prior to commit.
Comitting code in a checkout
In the SVN world you may have made changes to your checkout that need to be saved in the repository. One typically does so in this way:
$ svn commit -m'some description of whats being committed.'
Again, this looks very similiar in the Bazaar world:
$ bzr commit -m'some description of whats being committed.'
In both of these cases, the new changes will be saved to either the repository (SVN) or branch (Bazaar).
Section 2 - Using Branches to perform SVN migration
Bazaar supports a variety of other development methodologies that are foreign to SVN developers. These methodologies typically work much better than the SVN method. They are, however, a bit different from the CVS way.
Section 3 - Development methodologies
Loose Cannon Style
- Each developer makes and maintains their own branches.
- Developers merge each other ad-hoc
- No coordination of merges between branches
- Everyone gets their own itches scratched
- Developers do not need to like each other
- Highly competitive environment.
- Branches will become highly diverged.
- Users will be confused about which branches to follow
- Branches will likely diverge into different projects
Shared Branch Style
- There is one proto-branch that all developers can push to and from
- Developers may have local branches that individual features are worked on and then merged into the proto-branch
- The branch for users to follow is clear and obvious
- Development is not held up if one developer goes on vacation
- Developers can put code into the proto-branch without test cases being run.
- Contention for pushing into the proto-branch may become an issue if there is a large number of commit-happy developers.
The Lieutenant Style
- Needs to be combined with another style of development
- Each developer is responsible for a section of the codebase
- Developer collects merges and patches for their section of the codebase and puts it into a special branch
- Developers can specialize on a particular type of code
- Code is more likely to become peer reviewed
- Coordination for code that needs the involvement between two or more Lieutenants becomes a bit more complicated
- Development rate is slowed down a little.
The Patch Queue Manager Style
- Each developer makes their own branches
- The merge requests are submitted via email to a bot
- The bot merges the developers into the proto-branch
- Development is well coordinated
- Tests can be run automatically.
- Contention is reduced as changes are merged and not pushed
- Depends upon a server that can accept mail and expose a branch publically
- Can fall down under high loads
- Is not well documented