Bazaar

• Launchpad Entry:https://blueprints.launchpad.net/bzr/+spec/easy-workspace-setup

• Created: Date(2009-02-23T21:09:00Z) by IanClatworthy

• Contributors:

• Status: DraftBzrSpecification

Summary

Bazaar is a very flexible tool but that flexibility translates to complexity for new users trying to get started contributing to a project. Shared repositories, lightweight checkouts, bound branches and trees vs no-trees are sweet but its too much for a new user to digest. We need an easier way for users to bootstrap into a local workspace setup appropriate for the project's size & workflows and the user's planned contribution level.

Rationale

The best way for a Bazaar user to organise their workspace for a project depends on numerous factors including:

• user role: project owner vs core developer vs casual contributor
• workflows: particularly the workflow the project encourages/mandates for making contributions
• size: large projects have different resource requirements to small ones.

There are at least 4 common ways of organising one's workspace. For want of better names, let's call them:

• lightweight checkout
• standalone tree
• feature branches
• switchable sandbox.

Bazaar makes it easy to setup the first two models currently. It ought to make it easy to setup the last 2 models as well.

A brief description of each model follows.

Workspace models

Lightweight checkout

In this model, the working tree is local and the branch is remote. This is the standard model used by CVS and Subversion: it's simple and well understood.

To setup:

  bzr checkout --lightweight URL [my-dir]
  cd my-dir

To work:

  (make changes)
  bzr commit
  (make changes)
  bzr commit

Note that each commit implicitly publishes the change to everyone else working from that branch.

Standalone tree

In this model, the working tree & branch are in the one place. Unless a shared repository exists in a higher level directory, the repository is located in that same place as well. This is the default model in Bazaar and it's great for small projects (e.g. a plug-in).

To setup:

  bzr branch URL [my-dir]
  cd mydir

To work:

  (make changes)
  bzr commit
  (make changes)
  bzr commit

To publish changes to a central location:

  bzr push [URL]

As an alternative, a (normal) checkout can be used so that a separate publish step in not required.

Feature branches

In this model, there are multiple branches/trees, typically sharing a repository. One branch is kept as a mirror of "trunk" and each unit-of-work (i.e. bug-fix or enhancement) gets it's own "feature" branch. This model is ideal for most projects, particularly moderately sized ones.

To setup:

  bzr init-repo project
  cd project
  bzr branch URL trunk

To start a feature branch:

  bzr branch trunk featureX
  cd featureX

To work:

  (make changes)
  bzr commit
  (make changes)
  bzr commit

To publish changes to a mailing list for review & approval:

  bzr send

To publish changes to a public branch (that can then be registered as a Launchpad merge request, say):

  bzr push [URL]

As a variation, the trunk can be created as a checkout. If you have commit privileges on trunk, that let's you merge into trunk and the commit of the merge will implicitly publish your change. Alternatively, if the trunk URL is read-only (e.g. a http address), that prevents accidental submission this way - ideal if the project workflow uses an automated gatekeeper like PQM, say.

Local sandbox

This model is very simliar to the feature branches model except that the feature branches share a single working tree rather than having one each. This is the default model in git and it's useful for really large projects.

To setup:

  bzr init-repo --no-trees project
  cd project
  bzr branch URL trunk
  bzr checkout --lightweight trunk sandbox
  cd sandbox

To start a feature branch:

  bzr branch ../trunk ../featureX
  bzr switch ../featureX

The processes for making changes and submitting them are otherwise identical to those used for feature branches.

Proposed UI Enhancements

To do ...