BazaarX Design Document

Welcome to the BazaarX Design Document. The purpose of this document is to detail the design of BazaarX, both from a user facing point of view and from an internal architecture point of view.

Architecture

BazaarX is essentially built up of 3 classes of controllers:

The Window Controller
View Controllers
Sheet Controllers

The Window Controller handles all the views that appear in a window. The View Controllers handle the main content of each window, such as Repositories, Branches, Working Tree, Log, Diff, Annotate, Shelf. The Sheet Controllers handle all the actions that can be performed on a view.

Each of these controllers should be as self contained as possible, asking the window controller for the current branch/repository/working tree and sending out a notification for any events (most likely completion). This makes development easier as everything in the app is loosely coupled.

Accessing Bzr & Data Caching

Access to bzr is handled through the Objective-bzr framework. All access to any bzr functions should be treated as an extremely expensive operation. As such there should be extensive caching of data and refreshes should occur on a background thread, so as not to block the UI.

Objective-bzr works in an asynchronous fashion, with a completion block passed into most methods. For more information visit the Objective-bzr project page

Controllers

The controllers in BazaarX are:

BZXMainWindowController - holds the window, controlling display of views and sheets. Provides references to selected repository, branch and working tree
BZXRepositoriesViewController - manages a collection view of the repositories, standalone branches and checkouts in BazaarX.
BZXBranchesViewController - manages a list of branches in a repository, missing revisions in the branch from its parent and the ignores list for the branch.
BZXBranchViewController - handles the display of views related to an individual branch, such as the working tree, the log and the shelf.
BZXWorkingTreeViewController - manages the file management aspects such as adding files, creating folders, moving, renaming and displaying the status of files. Also allows a quicklook preview of the file.
BZXLogViewController - shows the log and handles the timeline for the branch.
BZXDiffViewController - manages diffs between two files, and merging those changes across.
BZXAnnotationsViewController - manages the display annotated files.
BZXShelfViewController - manages the branch's shelf. Displays changes on the shelf and in the branch as well as the shelving and unshelving of changes.
BZXAddRepositorySheetController - controls adding an existing repository to BazaarX.
BZXCreateRepositorySheetController - controls creating a new repository.
BZXBranchSheetController - controls branching an existing branch.
BZXCreateBranchSheetController - controls creating a new branch.
BZXCheckoutSheetController - controls checking out a working tree from a branch.
BZXBindSheetController - controls binding to a branch.
BZXSwitchSheetController - controls switching the bound branch.
BZXSendSheetController - controls sending a merge request via email.
BZXExportSheetController - controls exporting a branch.
BZXRemoveFilesSheetController - controls deleting a selected set of files.
BZXCommitSheetController - controls committing changes to a repository.
BZXCreateRepositorySheetController - controls uncommitting revisions.
BZXRevertSheetController - controls reverting to a certain revision.
BZXMergeSheetController - controls merging the current branch into another branch.
BZXRemergeSheetController - controls remerging merged files.

Repositories

When BazaarX is launched, the first thing visible is the repositories view. This shows all the repositories in a grid. You can add and remove repositories, modify them and view them. There are 2 special repositories for holding standalone branches and checkouts from remote repositories

Actions

Double clicking on an repository will slide the repository view out and slide in the branch list for that repository

Right clicking on a repository brings up a context menu:

Edit Repository…
Delete Repository

Edit Repository brings up the add repository sheet with details filled in. Delete Repository deletes the reference to the repository.

Pressing ⌘-backspace will also delete the reference to the repository

Add Repository

This sheet handles the adding of an existing repository. As such just the location is required, but an optional icon can be added.

Create Repository (init-repository)

This sheet handles creating repositories. A location is required. The user can then choose a repository format (default is the default format for the installed version of bzr).