Bazaar

Bazaar

 




Wiki Tools

  • Find Page
  • Recent Changes
  • Page History
  • Attachments

Differences between revisions 1 and 2
Revision 1 as of 2009-02-23 11:53:42
Size: 3051
Comment: Initial cut
Revision 2 as of 2009-02-24 10:13:04
Size: 4364
Comment: Refine the descriptions of the workspace models
Deletions are marked like this. Additions are marked like this.
Line 10: Line 10:
== Background == == Rationale ==
Line 21: Line 21:
 * standalone branch  * standalone tree
Line 25: Line 25:
A brief description of each follows. 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 ==
Line 46: Line 50:
=== Standalone branch === === Standalone tree ===
Line 48: Line 52:
In this model, the working tree, branch and repository are all in the one place. This is the "default" model of Bazaar and Mercurial. 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).
Line 67: Line 71:
As an alternative, a (normal) checkout can be used so that a separate publish step in not required.
Line 69: Line 75:
In this model, there are multiple branches/trees, typically sharing a repository. One branch is kept as a mirror of "upstream" and each unit-of-work (i.e. bug-fix or enhancement) gets it's own "feature" branch. This model is recommended by many DVCS users as the best way of working for most moderately-sized projects. 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.
Line 82: Line 88:
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]
}}}
Line 83: Line 104:
As a variation, the trunk can be created as a checkout. 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.
Line 87: Line 108:
The git model ... 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.
Line 103: Line 124:
== Proposed UI == The processes for making changes and submitting them are otherwise identical to those used for feature branches.

== Proposed UI Enhancements ==

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 ...