HOWTO

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