~bzr-loom-devs/bzr-loom/trunk

Loom, a plugin for bzr to assist in developing focused patches.

Copyright (C) 2006 Canonical Limited.

This program is free software; you can redistribute it and/or modify

it under the terms of the GNU General Public License version 2 as published

by the Free Software Foundation.

This program is distributed in the hope that it will be useful,

but WITHOUT ANY WARRANTY; without even the implied warranty of

MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the

GNU General Public License for more details.

You should have received a copy of the GNU General Public License

along with this program; if not, write to the Free Software

Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301 USA

A quick guide to using looms

++++++++++++++++++++++++++++

Overview

========

Loom is a Bazaar plugin to assist in developing focused patches. It adds a

'loom' to a bzr branch. A loom allows the development of multiple patches at

once, while still giving each patch a branch of its own.

Installation

============

Loom is most easily installed by symlinking its source directory to

``~/.bazaar/plugins/loom``. Alternatively, you can install it for the entire

machine using ``python setup.py --install``.

You can verify that loom is installed by running ``bzr plugins`` and looking

for loom in the output.

Getting Started

===============

1. First, convert an upstream version branch into a loom. In this example, I

   call the upstream branch ``upstream``. In your upstream branch, run::

       % bzr nick upstream

       % bzr loomify

   This will convert your branch to a loom - from this point forward the loom

   plugin is required to work on this branch. It will also create a thread

   called ``upstream``, which will act as a pristine branch to track the

   upstream code.

   The ``bzr nick`` is used to index into the threads in the loom. The current

   thread is the bzr nick for the branch and is recorded in commits as such.

   You can use ``bzr nick newname`` to change the name of a thread.

   If you ``bzr push`` to a new branch now, it will make the remote branch a

   loom, as well. However, if you push to an existing, normal bzr branch, then

   the current thread of your loom is what will be pushed. You can use this to

   publish individual threads for people that do not have the loom plugin.

2. Now you can create another thread, which will represent the first patch you

   are building on top of the upstream code::

       % bzr create-thread "demo-patch"

   This creates a new thread, named ``demo-patch``, above your current thread

   and switches you onto the new thread. You can see which thread you are

   currently on using the ``show-loom`` command::

       % bzr show-loom

       =>demo-patch

       upstream

   The output represents a stack of threads, with the ``=>`` marker indicating

   the current thread. At the top of the thread stack is the thread you are

   working towards, below that are the threads that it depends upon, and at the

   bottom is the thread that represents the upstream code being built upon.

Working with the loom

=====================

You can now work with the thread you are in just like a normal bzr branch -

you can pull work from a normal branch into it, perform commits, uncommits,

look at bzr log, etc. There are, however, additional commands that the loom

plugin provides - they are covered in the following sections. For more

information on them, use ``bzr help command-name``.

Starting a new patch

--------------------

When you make a new patch, you need to decide where in the loom it should go.

Best practice is to put the thread for this new patch as close to the upstream

as makes sense. For instance, if you are a Debian maintainer with the following

loom::

    =>debian

      configure-update

      compilation-fix

      upstream

...and you have received a bug report and patch that corrects a typographical

error in the manual, you could put this in one of the existing threads - but

none fit that well. You could put it above the ``debian`` thread, but it does

not depend on the ``debian`` thread; however, the ``debian`` thread *does*

depend on it, because the ``debian`` thread represents what you will be

uploading to the distro. You could put it above ``configure-update``, above

``compilation-fix``, or right above ``upstream``.

So, where should you put this new thread?

If none of the threads are in the process of being merged into upstream, and

this is something you plan to send upstream immediately, then the best place

for this new thread is probably directly above ``upstream``. On the other hand,

if the ``compilation-fix`` and ``configure-update`` threads are already in the

process of being merged into upstream, then the best place for the new thread

is directly above the ``configure-update`` thread.

To create a new thread above the ``configure-update`` thread, use the

``down-thread`` command once to switch to the ``configure-update`` thread, and

then invoke ``create-thread``::

    % bzr down-thread

    % bzr create-thread documentation-fixes

Now you can apply the patch and commit it::

    % patch -0 < doco-fix.patch

    % bzr commit

Updating to a new upstream version

----------------------------------

When upstream makes a new release, you need to bring their changes into your

baseline thread - the bottom thread, and then merge the changes up through your

loom to the top thread.

1. First, use ``down-thread`` repeatedly to move down to the bottom thread of

   the loom (this will be made easier in the future with an automatic mode of

   operation)::

       % bzr down-thread

       % bzr down-thread

       % bzr down-thread

       % bzr show-loom

         debian

         configure-update

         compilation-fix

       =>upstream

2. Next, pull the new upstream release. You can use ``bzr pull`` or ``bzr

   merge`` for this, depending on whether you want the ``upstream`` branch to

   be a clone of the upstream branch you are tracking, or to reflect the times

   that you have updated to upstream::

       % bzr pull UPSTREAM-URL

3. Now, integrate the changes from upstream into your loom by moving up through

   your threads using the ``up-thread`` command.  ``up-thread`` will

   automatically perform a merge and commit for each thread in your loom,

   moving up one thread at a time and stopping after it has committed to the

   top thread::

       % bzr up-thread

       All changes applied successfully.

       Moved to thread 'compilation-fix'.

       Committing to: /demo

       Committed revision 140.

       All changes applied successfully.

       Moved to thread 'configure-update'.

       Committing to: /demo

       Committed revision 141.

       All changes applied successfully.

       Moved to thread 'debian'.

       Committing to: /demo

       Committed revision 142.

   If you would prefer to commit the change to each thread yourself, instead of

   letting ``up-thread`` perform this automatically, just specify the

   ``--manual`` flag.  In this mode of operation, the merge will still happen

   automatically, but you'll have the opportunity to inspect the changes before

   committing them yourself.  Continue using ``up-thread`` and committing

   until you've reached the top, or drop the ``--manual`` flag to automatically

   perform the merge and commit on the remaining threads::

       % bzr up-thread --manual

       All changes applied successfully.

       Moved to thread 'compilation-fix'.

       % bzr diff

       % bzr st

       % bzr commit -m 'New upstream release.'

       Committing to: /demo

       Committed revision 140.

       % bzr up-thread

       All changes applied successfully.

       Moved to thread 'configure-update'.

       Committing to: /demo

       Committed revision 141.

       All changes applied successfully.

       Moved to thread 'debian'.

       Committing to: /demo

       Committed revision 142.

4. Once at the top, you are fully updated to upstream and you've adjusted every

   thread to the new release. This is a good time to record your loom, so that

   you can push a new release::

       % bzr record "Update to 1.2."

After upstream has merged your patch

------------------------------------

When you are performing an update to upstream and they have merged your patch,

your thread will suddenly lose all its changes. Lets say in the example above

that upstream has merged your changes in the ``configure-update`` thread. When

you update to that thread, a call to ``diff -r below:`` will show no changes::

    % bzr up-thread

    All changes applied successfully.

    Moved to thread 'configure-update'.

    % bzr diff -r thread:

Because there are no changes to the thread below, this thread has been fully

merged.  Unless you are planning further configure changes, you don't need it

in your stack anymore. You remove a thread using the ``combine-thread``

command. ``combine-thread`` is the reverse of ``create-thread`` - where

``create-thread`` makes a new thread above the current one, ``combine-thread``

combines the current thread into the one below it::

    % bzr show-loom

      debian

    =>configure-update

      compilation-fix

      upstream

    % bzr combine-thread

    % bzr show-loom

      debian

    =>compilation-fix

      upstream

Showing a single patch

----------------------

You can show a single patch without knowing the names of other threads by using

the ``below:`` and ``thread:`` revision specifiers::

    % bzr show-loom

      debian

    =>configure-update

      upstream

    % bzr diff -r below:configure-update..thread:configure-update