Overview

For squid 3.x we are migrating the development trunk and web code browsers to Bazaar.

Bazaar

Bazaar is a distributed VCS written in python. It offers both drop-in CVS replacement workflow (use checkouts to work on code), and full distributed workflow (every copy is a new branch), up to the user to work as they want.

Installation

Bazaar is available in most O/S's these days: http://bazaar-vcs.org/Download.

Things to install (as a user):

• bzr
  • version 1.2 or later recommended for best performance, but 1.0 or later is sufficient.
• bzr-email (as a package it may be a bit old, try:

  • mkdir -p ~/.bazaar/plugins/ && bzr branch http://bazaar.launchpad.net/~bzr/bzr-email/trunk/ ~/.bazaar/plugins/email Then do 'bzr help email' and setup any local machine configuration you need in bazaar.conf - such as mailer to use etc.

• bzrtools
  • adds the cbranch plugin, making it easier to work with a local repository

Repository Location

For committers:

bzr+ssh://USERNAME@bzr.squid-cache.org/bzr/squid3/trunk

For anonymous access/mirroring/etc:

http://bzr.squid-cache.org/bzr/squid3/trunk

Also mirrors are available at:

• https://code.launchpad.net/~squid/squid/squid3-trunk

• https://code.launchpad.net/~squid/squid/3.1

• https://code.launchpad.net/~squid/squid/SQUID_3_0

• Other developer code branches: https://code.launchpad.net/squid/

Web view

Web view:

RSS feed:

• http://bzr.squid-cache.org/bzrview//squid3/SQUID_3_1/atom

• http://bzr.squid-cache.org/bzrview//squid3/SQUID_3_0/atom

Recipes

Let bzr know who you are

bzr needs to know your identity. A bzr identity is your name & email address.

bzr whoami "Your Fullname <email@address.domain>"

or to verify what bzr thinks your identity is

bzr whoami

If you don't do this bzr guesses based on your account and compuer name.

Setup a mirror/development environment

This can be done many ways. The following recipe gives you a local repository separate from the working trees, which can be used to develop many branches in an offline manner. It makes use of cbranch command from bzrtools to save a bit of time in this kind of setup.

# create a local repository to store branches in
bzr init-repo --no-trees ~/squid-repo
# Create a place where to keep working trees
mkdir -p ~/source/squid
# Configure ~/.bazaar/locations.conf mapping the working trees to your repository
cat >> ~/.bazaar/locations.conf << EOF
[/home/USER/source/squid]
cbranch_target=/home/USER/squid-repo
cbranch_target:policy = appendpath
[/home/USER/source/squid/trunk]
public_branch = http://bzr.squid-cache.org/bzr/squid3/trunk/
EOF

Checkout an existing branch to work with on

After your setup is done its time to checkout the first branch you are going to work on directly, or create a child branch for. In most cases this will be the trunk branch.

# get the Squid-3 trunk into this repository
# If you have commit access to trunk:
export TRUNKURL=bzr+ssh://bzr.squid-cache.org/bzr/squid3/trunk
# otherwise:
export TRUNKURL=http://bzr.squid-cache.org/bzr/squid3/trunk
cd ~/source/squid
bzr cbranch --lightweight $TRUNKURL trunk
#
# bind the local copy of trunk to the official copy so that it can be used to commit merges to trunk and activate the 'update' command
cd trunk
bzr bind $TRUNKURL

Make a new child branch to hack on

First follow the instructions above to setup a development environment

Now, in the below example, replace SOURCE with the branch you want your new branch based on, and NAME with the name you want your new branch to have in the following:

cd ~/source/squid
bzr cbranch --lightweight ~/squid-repo/trunk NAME
cd NAME
bzr merge --remember ~/squid-repo/trunk

Share the branch with others:

you want to share (read-only) the branch with others also do:

cd NAME
bzr push --remember PUBLIC_URL

e.g. if you were to use the launchpad.net bzr hosting service:

bzr push --remember bzr+ssh://bazaar.launchpad.net/~USER/squid/NAME

to update the shared copy in the future all you need to run is

bzr push

bring a branch up to date with it's ancestor

First update your copy of the ancestor;

cd ~/source/squid/trunk
bzr update

Then merge the changes into your child branch:

cd ../NAME
bzr merge
[fix conflicts if any]
bzr commit -m "Merge from trunk"

Then continue hacking on your branch.

If bzr merge complains on not having a source to merge from then use the following merge command once

bzr merge --remember ~/squid-repo/trunk

If the bzr update step runs very quick and doesn't seem to bring in any updates then verify that the main branch is bound to the main repository location, not only having it as parent. "bzr info" should report something like the following:

Lightweight checkout (format: dirstate or dirstate-tags or pack-0.92 or rich-root or rich-root-pack)
Location:
       light checkout root: .
  repository checkout root: /home/henrik/squid-repo/squid3/hno/trunk
        checkout of branch: bzr+ssh://bzr.squid-cache.org/bzr/squid3/trunk/
         shared repository: /home/henrik/squid-repo/squid3
Related branches:
  parent branch: bzr+ssh://bzr.squid-cache.org/bzr/squid3/trunk/

If "checkout of branch" indicates your local repository instead of the main source then you need to bind the tree. But first verify that you really are in the main working tree and not your own branch..

bzr bind bzr+ssh://bzr.squid-cache.org/bzr/squid3/trunk/ 

Submit a patch for inclusion in the main tree or discussion

Verify the contents of your branch

bzr diff -r submit: | less

If it looks fine then generate a diff bundle and mail it to squid-dev

bzr send --mail-to=squid-dev@squid-cache.org

alternatively if that fails try:

bzr send -oYourFeatureName.merge

Then manually email the file YourFeatureName.merge as an attachment to squid-dev mailing list.

It's also possible to cherrypick what to send using the -r option. See bzr help revisionspec for details

Commit directly to trunk

Make sure you have a clean up to date trunk tree:

cd ~/squid/source/trunk
bzr status
bzr update

bzr status should show nothing. If it shows something:

bzr revert

If you are merging a development branch:

cd ~/squid/source/trunk
bzr merge ~/squid/source/childbranchFOO
bzr commit -m "Merge feature FOO"

If you are applying a plain patch from somewhere:

cd ~/squid/source/trunk
bzr patch PATCHFILE_OR_URL
bzr commit
# edit the commit message

If you are back/forward porting a specific change:

cd ~/squid/source/trunk
bzr merge -c REVNO OTHERBRANCH_URL
bzr commit
# edit the commit message

cherry pick something back to an older release using CVS

Generate a diff using bzr:

bzr diff -r FROMREVNO..TOREVNO > patchfile

or if its a single commit

bzr diff -c COMMITREVNO > patchfile

and apply that to cvs with patch:

patch -p0 <patchfile

Merge another branch into yours

You can merge in arbitrary patterns, though because bzr 1.0 defaults to 'merge3' for conflict resolution the best results occur if a hub-and-spoke system is used where each branch only merges from one other branch, except when changes from a 'child' branch are completed and being merged into that branch.

cd ~/squid/source/DESTINATION
bzr merge ~/squid/source/SOURCE_OF_FOO
bzr commit -m "Merge feature FOO"

NP: The DESTINATION branch must be a local checkout of files to patch. The SOURCE branch may be the folder, bundle, or online URL of another branch.

diffing against arbitrary revisions/branches

To diff against a different branch there are several options. The most common and most useful one is 'ancestor' and will give you the diff since the most recent merge of that other branch. If there is a third branch that has been merged into both your branch and the one you are diffing, it's changes will appear in the diff. There is work underway to provide diffs that handle any merge pattern more gracefully - see merge-preview as the start of the work in bzr.

cd MYBRANCH
bzr diff -r ancestor:URL_OF_OTHER_BRANCH

Another useful option is to diff against the current tip of a branch, which will show things that you have not merged from that branch as 'removed' and things you have created locally as 'added':

cd MYBRANCH
bzr diff -r branch:URL_OF_OTHER_BRANCH

You can also diff against arbitrary revnos in the other branch:

cd MYBRANCH
bzr diff -r 34:URL_OF_OTHER_BRANCH

For more information:

bzr help revisionspec

Helper scripts

While bzr provides simple operation access. So did CVS in most cases. The problem is, mistakes are easier too. We need to provide some recipes as easy to use scripts.

• testing a branch before submission

  • ./test-builds.sh in squid source. Runs configure and build permutation tests.

• cleaning up a branch or patch for auditing

  • ./scripts/srcformat.sh *** provided you have the right astyle version not to alter all the code.