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.

Note
This is a first hack. The commands haven't been tested. This document hasn't been run by upstream bzr or hg users for feedback and corrections.

Setup

cvs	hg	bzr
cd	cd	cd
		mkdir ~/.bazaar
	~/.hgrc	bzr whoami "NAME <EMAIL>"
mkdir fedora	mkdir fedora	bzr init-repo --trees fedora

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

cvs	hg	bzr
cd fedora	cd fedora	cd fedora
export CVSROOT=:pserver:anonymous@cvs.fedora.redhat.com:/cvs/extras
cvs checkout [PACKAGE]	hg clone http://fedoraproject.org/repos/[PACKAGE]	bzr branch http://fedoraproject.org/repos/[PACKAGE]

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: bzr checkout --lightweight which is more similar to the cvs usage but it won't work with read-only repositories. In the future, there may be a bzr checkout --shallow command which does not need to lock the repository and so it can be used in this manner.

Read-write checkout

CVS Style

cvs	hg	bzr
cd fedora	(N/A)	cd fedora
export CVSROOT=:ext:LOGIN@cvs.fedora.redhat.com:/cvs/extras
cvs checkout [PACKAGE]		bzr checkout --lightweight sftp://fedoraproject.org/repos/[PACKAGE]
		-- Make Changes --
cvs update		bzr update
		-- Resolve conflicts --
cvs commit -m "Log Message"		bzr commit -m "Log Message"

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

cvs	hg	bzr
(N/A)	cd fedora	cd fedora
	hg clone ssh://fedoraproject.org/repos/[PACKAGE]	bzr checkout sftp://fedoraproject.org/repos/[PACKAGE]
	hg merge ssh://fedoraproject.org/repos/[PACKAGE]	bzr update
		-- Resolve conflicts --
	hg commit	bzr commit
	hg push ssh://fedoraproject.org/repos/[PACKAGE]	(Done as part of commit)

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

cvs	hg	bzr
(N/A)	cd fedora	cd fedora
	hg clone ssh://fedoraproject.org/repos/[PACKAGE]	bzr checkout sftp://fedoraproject.org/repos/[PACKAGE]
		-- Make Changes --
	hg commit -m "Disconnected Change"	bzr commit --local -m "Disconnected Change"
		-- Reconnect to the network --
	hg merge ssh://fedoraproject.org/repos/[PACKAGE]	bzr update
		-- Resolve any conflicts --
	hg commit -m "Sync with Remote Changes"	bzr commit -m "Merge Local changes with Remote"
	hg push	(Done as part of commit)

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

Feature Branches

cvs	hg	bzr
(N/A)	cd fedora	cd fedora
	hg clone ssh://fedoraproject.org/repos/[PACKAGE]	bzr branch sftp://fedoraproject.org/repos/[PACKAGE]
		-- Make Changes --
	hg commit -m "Work on Feature"	bzr commit -m "Work on Feature"
		-- Repeat previous two steps until done --
	hg merge ssh://fedoraproject.org/repos/[PACKAGE]	bzr merge --remember sftp://fedoraproject.org/repos/[PACKAGE]
		-- Resolve any conflicts --
	hg commit -m "Sync with Remote Changes"	bzr commit -m "Sync with remote changes"
	hg push ssh://fedoraproject.org/repos/[PACKAGE]	bzr push

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

cvs	hg	bzr
cd fedora	cd fedora	cd fedora
export CVSROOT=:ext:LOGIN@cvs.fedora.redhat.com:/cvs/extras
cvs co [PACKAGE	hg clone ssh://fedoraproject.org/repos/[PACKAGE]	bzr branch sftp://fedoraproject.org/repos/[PACKAGE]
		-- Make Changes -- For Fedora Packages, this will mostly be adding and removing patches and updating the spec file. This is a case where you do use some cvs commands (cvs add; cvs remove) even though you cannot talk to the repository.
	hg commit -m "Work on Feature"	bzr commit -m "Work on Feature"
		-- Repeat previous two steps until done
	hg merge ssh://fedoraproject.org/repos/[PACKAGE]	bzr merge --remember sftp://fedoraproject.org/repos/[PACKAGE]
cvs diff -u > changes-to-email.diff	hg bundle > changes-to-email.bundle	bzr bundle > changes-to-email.bundle
		-- Send changes to maintainer; maintainer applies using: --
patch -p0 < changes-to-email.diff	hg unbundle changes-to-email.bundle	bzr merge changes-to-email.bundle

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 hg export 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