Infrastructure/VersionControl/WorkFlow

= Common Operations =

Introduction
This page describes common operations on the Fedora Repositories and gives example sequences of commands to run on each.

This document presently compares CVS, mercurial, and Bazaar commands purely as the sequence of steps it takes to get something done.

Setup
Bazaar has a concept of "repositories" which are optimized storage locations for branches. By creating a repository to store all our Fedora branches in, we save space when branches share common ancestors. The --trees option to init-repo tells the repository to create working trees by default. This is what you want when creating repositories that you will be doing work in. Repositories for shared checkouts will often dispense with the working trees to save space.

Anonymous checkout
In this scenario, Bazaar and Mercurial will both checkout a full read-only version of the remote package's revsions. (repository in Mercurial's terminology, branch in Bazaar's). cvs will only checkout the head revision of the package. Bazaar has a checkout command:  which is more similar to the cvs usage but it won't work with read-only repositories. In the future, there may be a  command which does not need to lock the repository and so it can be used in this manner.

CVS Style
The CVS-style checkout only checks out one revision from the repository/branch. All previous revisions live on the server. Refering to historical data or making commits has to go to the server. In a tree like Fedora uses, where most branches are very small and there's relatively few revisions, it makes more sense to use a Distributed Style checkout rather than CVS style. The one time cost of checking out the complete branch is small compared to having to hit the network when using diff, log, and other commands that need historical information.

Distributed Style
The distributed style sends the complete revision history for the branch as well as the last revision. The Mercurial and Bazaar commands are slightly different as Bazaar's "checkout" command binds the checkout to a remote repository location. When commiting changes to the repository, the branch will be committed to both locally and remotely automatically. The hg clone command does not do this binding so committing will be a two step process. Please see Branching for usage of Bazaar's "branch" command which is equivalent to Mercurial's clone.

Branching
There are several uses for branching in the Fedora Package repositories:


 * 1) To be able to disconnect from the network and still make commits to revision control.  Then be able to sync these commits to the networked repository when you're back on the network.
 * 2) To be able to create a branch of the main repository and hack on changes for a while.  Then merge the changes back into the mainline when done.
 * 3) To be able to branch a project that you have read-only access to, commit changes into your local repository, and then submit a the changes to the maintainer.

Short Term Disconnected Operations
For short term disconnected operations, bzr can make local commits only instead of committing to both the local and remote branches.

Feature Branches
For long term feature work, creating your own branch that you can commit to is best. The Bazaar and Merurial commands are nearly identical in this case.

Working with Read-Only Repositories
The Bazaar and Mercurial bundles contain information present in a traditional patch as well as extra information pertinent to the VCS such as permissions and ancestry. This allows the bundle format to do things that a simple patch cannot. However, Mercurial bundles are not human-readable. If you want something that can be read by others you need to use  which doesn't contain the extra information.

Summary
Bazaar and Mercurial are much more similar than CVS. Bazaar has several nice features: commands that make a centralized model (a la cvs) more natural and the "repository" that optimizes space between branches. Mercurial, on the other hand, has predictability in its commands: a checkout will always be "hg clone"; committing to a remote repository will always do hg commit; hg push.

Links
Blog comparing mercurial to bzr http://sayspy.blogspot.com/2006/08/comparing-mercurial-to-bazaar-ng.html Bazaar document describing how to use CVS-style centralized management http://bazaar-vcs.org/Tutorials/CentralizedWorkflow