Getting objects to talk to one another in Objective-C is a easy as passing a message from one to the other. These messages are typically passed through the message-invocation mechanism of using the square-braces to bind a message and arguments to a receiver. Most of the time this is a perfectly reasonable way to communicate. However there are times when you need objects to communicate without having explicit knowledge of one another.

In this post we’ll look at three ways to allow your objects to communicate with each other in a highly-decoupled manner using the Cocoa frameworks. Cocoa provides three common ways of connecting objects for messaging: Notifications, Key-Value Observation and delegate pattern.

Notifications

Both Cocoa and Cocoa Touch provide a notifications framework built on two classes: NSNotificationCenter and NSNotification. The former contains a singleton instance, (via the defaultCenter method) with which observers register themselves and observables post notifications. The latter is the “envelope” for the notification which can contain an NSDictionary instance of customized data as its payload.

When an object registers for notifications, it specifies a notification to listen for (as a NSString) and, optionally, a target object. If the target is set to an object, only notifications posted by that object will be received. If the target object is set to nil, any object posting that notification will be sent to the receiver. Senders can optionally include a NSDictionary instance filled with domain-specific objects. You can use this as a way to further parameterize a notification, or eschew it altogether.

Consider the example below:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

@implementation Foo
- (void)init {
  if (self = [super init]) {
    [[NSNotificationCenter defaultCenter] addObserver:self
                                             selector:@selector(didReceiveNote:)
                                                 name:@"TheBigNotification"
                                               object:nil];
  }
  return self;
}
 
- (void)didReceiveNote:(NSNotification *)notification {
  NSLog(@"Hey, I got a notification with user info: %@", [notification userInfo]);
}
@end
…
@implementation Bar
- (void)doSomething {
  NSLog(@"I'm up to something!");
  NSDictionary *stuff = [NSDictionary dictionaryWithObjectsAndKeys:@"foo", @"bar", nil];
  [[NSNotificationCenter defaultCenter] postNotificationName:@"TheBigNotification"
                                                      object:nil
                                                    userInfo:stuff];
}
@end

Here the Foo class registers itself as a notification receiver for the notification named “TheBigNotification” on any object. The Bar class will post the same notification when the doSomething method is invoked.

We could have been much more specific about which object to observe, but I think this violates one of the key features of notifications which is that the sender and receiver are decoupled. To me if the receiver is going to go to the trouble of listening for notifications from a specific object, you’d be better off declaring a custom protocol and using the delegate pattern (explained below).

While at the 2009 WWDC, I had a chance to pick the brains of some Apple engineers and one of them told me that notifications are really intended for one-to-many broadcasts. I think that’s a great rule of thumb, because the code can really feel like overkill for single object-to-object messages. However, I’d add one more clause to that rule which is that notifications work for one-to-one messages when you would otherwise have to pass instances around of delegates just to connect objects.

As an example, consider an iPhone application with a stack of view controllers in a UINavigationController instance. If you have a view controller several steps removed from another view controller (i.e. one is a further up the stack in a tab bar controller) and it needs to call some method back to the view controller lower down in the stack, each intermediate object would need a reference to the delegate class just to pass it down the line. This seems like the worst kind of encapsulation breakage since you’re forcing a bunch of otherwise-unrelated classes to have knowledge of a class they don’t even use.

Maybe it’s my long track-record with Java, but I pay attention to the classes I import and I like to keep that list as short as possible. The more classes know about each other, the more difficult it is to modify them.

There’s one final thing worth knowing about the NSNotificationCenter, and that is how it works with threads. When one object posts a notification, that call blocks while the notification is delivered to all targets. This means that you want your notification-handling code in the receiving object to be as quick as possible. If you can live with deferred notifications and want to avoid the synchronous nature of notification delivery, you can use the NSNotificationQueue instead.

Key-Value Observation

When I first read about, and used Key-Value Observation (KVO) it seemed like magic. You simply point one object at another and say “I’d like to know when this attribute changes” and Cocoa handles all of the notifications and threading automatically. Genius!

KVO also allows you to use a special syntax when specifying the attributes you want to observe so that you can register with an object and traverse its object graph. Let’s look at the classic customer/orders/line items example. If you want to know when changes are made to any line items in an order you would observe changes in the order like so:

1
2
3
4
5

Order *order = [self anyOrder];
[order addObserver:self
        forKeyPath:@"lineItems"
           options:NSKeyValueObservingOptionNew | NSKeyValueObservingOptionOld
           context:nil];

Whenever you register for KVO, you must implement the method - observeValueForKeyPath:ofObject:change:context:. Unlike notifications, you don’t get to specify a selector. This means that if you’re object is observing several other objects, you will have to inspect the object given in the callback method and dispatch appropriately.

Key paths have a ton of flexibility including the ability to traverse deep object graphs and observe aggregate functions on a collection (e.g. observe the max date of all of a customer’s orders). Check out the Key-Value Programming Guide for details, which is an indispensable reference.

KVO works like notifications in that the thread that invokes the change will block until all observers have been notified and their callback methods have been invoked. Unlike notifications, there is no built-in asynchronous KVO-triggering mechanism unless you explicitly mutate properties in another thread using something like the detachNewThreadSelector:toTarget:withObject: class method of NSThread.

For classes to be key-value observable they must be, what the documentation calls, “key-value compliant”. This generally means that each observable property exposes certain methods for accessing and mutating them. Again, the KVO guide is your go-to reference.

KVO is structurally similar to notifications, but is really intended for fine-grained messaging, generally around your model classes. Notifications are intended for broader application-level events. Both mechanisms give you a way to decouple classes that would otherwise need more intimate knowledge of one another.

Consider the simple case of managing a tabular view of line items in an order. When a user adds a line item, removes a line item or updates the quantity of a line item we want a field showing the total price to be updated. Without KVO we would need to add extra logic in our event-handing for the table view to also update the total field. With KVO our event-handling logic can simply focus on updating the underlying model. The total field will simply observe the total cost of the order and be updated appropriately. Now if we want to remove the total field or perhaps add another view of total information, we don’t have to touch the original event-handing code.

Delegates

If you’ve spent any time with the Cocoa docs you’ll run across The Delegate Pattern. This thing is like the quark—it is the fundamental building block of the Cocoa APIs. Conceptually, it’s really pretty simple. A delegate is simply an object that provides custom behavior for another object, often by implementing a specific protocol.

Let’s return to our running example. A table view of line items in an order has to handle a lot of things such as rendering each cell, handling scrolling, managing user-generated events and so on. These features are common enough that they are simply part of the table view class itself. What is specific to your application is the data that goes in those cells and the actions to be taken for user-generated events. Cocoa solves this by providing protocols for delegating that behavior to custom classes. In the case of providing data, a data-oriented delegate would be queried by the table view for the total number of rows, appropriate object to put in each row, the column headers, etc. In the case of event-handling, the table view will forward events to the event-handling delegate.

Notifications use the NSNotificationCenter (or by proxy, the NSNotificationQueue) as an intermediary between message-senders and message-receivers. KVO uses the observed object as the intermediary. In the delegate model there is no intermediate object, but you still have relatively decoupled code because the object that invokes methods on the delegate has no knowledge of what class of object it’s dealing with. Put another way, you could remove all of the classes in your project that implement a particular delegate protocol, and the class that uses the delegate would still compile correctly.

The delegate pattern isn’t so much about decoupling which objects are communicating with each other, as much as decoupling the classes of those objects. This doesn’t make it any less powerful than the other two methods. In a lot of cases a simple delegate model is much more straightforward and preferable the alternatives.

The delegate pattern is Cocoa’s version of dependency injection. The object receiving the injected dependency has no idea of the type (and by extension, the implementation) of the object it is receiving, only what it’s capabilities are via a contract specified as a protocol. This is basic polymorphism where the interface and the implementation are separated to reduce coupling.

Delegating is a popular alternative to sub-classing. It is a preferred alternative because it’s less likely to break encapsulation. If customization is done through subclassing it can be difficult to know which methods to override and implement, and easy to break the parent class. This is why Java provides all sorts of safety features like marking methods abstract and final. However that is simply more of a headache to deal with and using polymorphism would be a much better design.

So there you have it, three ways to keep your code flexible and loosely-coupled!

Resources

• Apple’s Notification Programming Topics
• Apple’s Key-Value Coding Programming Guide
• Apple’s Cocoa Fundamentals
• Mike Ash’s Well-Reasoned Critique of KVO Design

The iPhone Ecosystem

We live in a very interesting time for application development. The distinctions between desktop, browser and mobile applications are blurring more and more every day. “Ubiquitous platform” applications, like Evernote, are where the future is because it reduces the major hurdle of access for users. As time goes on users are going to expect applications to be available in a bunch of different ways that all need to work together.

The common way to do this is base the application on shared-state accessed via an HTTP-based API. This makes it relatively easy to create apps for various devices as well as offer up a public API for others to use. An interesting side-effect of this is that the API, the shared-state and data behind it become the differentiator between products. The end-user client software is simply the packaging, turning the stand-alone application market into something more akin to the “razors and razor-blades model”.

Okay, none of this should be earth-shattering news to anyone. You should be prepared to write more apps that are integrated with one (or possibly more) “backend services”. These services will, as likely as not, be connected over HTTP. As an iPhone developer you should know how to do this in your sleep.

The Evri API is absolutely crucial to the EvriVerse phone application. Without it, the app does nothing of interest on its own. Our iPhone application is merely one kind of presentation of our web APIs. I don’t think that’s unique. What good would Tweetie be without Twitter?

Dealing with Web APIs

An unfortunate fact of integrating with web APIs is that they are, relatively speaking, slow. We don’t want the user to get frustrated and give up on our app because they have their flow continually disrupted by waiting for data.

There are some things you can do to mitigate the latency costs, if you control the API such as using some sensible caching parameters. However, especially if you don’t control the web API, the bulk of what you should focus on is concurrency within your application. The biggest arrow in your quiver is figuring out how to turn unnecessarily serial operations into parallel ones. Now keep in mind that the iPhone doesn’t support true multi-core concurrency. What I’m talking about is taking advantage of the I/O wait times that are inherently part of working with a high-latency I/O source (the web).

Coming from a Java background, using threads seemed like a pretty natural approach and after reading the docs on the NSThreadclass I felt pretty confident I knew how to make it work. However, I was surprised by how quickly the code complicated. There is a lot to like about Objective-C, but I sorely miss Ruby’s blocks and even Java’s inner-classes. In Objective-C you connect methods together dynamically by handing objects selectors. The problem with this is that it’s difficult to tell the high-level methods from the low-level callback methods just by looking at your class definition. Yes, you can use special comments and the like, but if you’ve worked in a language that has structural support for this differentiation, moving to a language without it feels like losing an arm.

So instead of managing your own threads, let Cocoa Touch do the work for you. The NSURLConnection class is inherently asynchronous—you can fire a request and immediately move one with your life. Now you just need a little structure for handling the response and getting it back into your views.

The EvriApi

We tried to push as much of the mechanics of URL-handling into a separate code-base we call EvriApi. A good bit of the design was inspired by Matt Gemmell’s MGTwitterEngine, so I can’t claim that I came up with the whole idea myself.

We wanted the API to be as simple to work with as possible. Each API call has the same structure:

• Each API method takes zero-or-more domain-specific parameters, a selector and a target object.
• Each API method returns a unique request identifier
• The target object will have the given selector called when the request completes, and will be given an instance of the EvriAPIResponse class.
• If the response is successful (check [response success]), the payload of the request is retrieved as a domain-object
• If the response is unsuccessful, check the error message on the response
• Requests can be cancelled by handing the request identifier back to the API
• Attempts to cancel already-completed requests do nothing

The NSURLConnection class makes asynchronous requests by default, and uses the familiar delegate model for handling the response. When a client invokes an API method, it returns immediately with a unique identifier (as a NSString instance) and the request is initiated on another thread which is handled automatically by NSURLConnection. The client is responsible for keeping track of that and using it to cancel any outstanding requests.

When the request completes, the body of the response is parsed using the NSXMLParser class. The parser is given one of our specialized XML handlers as a delegate. These handlers deal with the XML event-stream and produce a model object or collection of model objects. The framework then packages this up into an EvriAPIResponse instance and invokes the selector given in the original request on the target given in the original request.

Wiring it Up

The EvriVerse app is primarily a “productivity” style application. In Interface Guidelines-parlance this means that we use a lot of hierarchical navigation. In general we have no more than one or two API calls associated with a particular view controller.

The common pattern for handling a user-initiated action that requires an API call is:

1. A new view-controller is instantiated and displayed, typically with an activity indicator visible
2. User-interaction is disabled on the new view controller
3. The new view controller is displayed (usually by pushing it on the navigation controller stack).
4. A request is submitted to the EvriApi, setting the new view controller as the target and some special method as the target selector.
5. The request ID from the EvriApi is given to the newly-created view-controller
6. When the API request finishes, the handler method on the new view-controller executes, handling both success and failure cases. It also re-enabled user interaction on the view.
7. If the user navigates back before the request has completed, any outstanding requests are cancelled. This is usually handled in the viewWillDisapper:(BOOL)animated method of the view controller.

Stepping back, the actors and interactions look something like this:

In code (snippets) it might look something like this:

1
2
3
4
5
6
7
8
9
10
11
12

// our parent view controller
@implementation ParentViewController
- (void)didSelectEntity {
  ChildViewController *cvc = [[[ChildViewController alloc] init] autorelease];
 
  [self.navigationController pushController:cvc animated:NO];
 
  NSString *requestId = [EvriApi fetchEntityByURI:entity.uri
                                  performSelector:@(didReceiveEntityResponse:)
                                         onTarget:cvc];
}
@end

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

@interface ChildViewController : UITableViewController {
  NSString *requestId;
}
 
@property (nonatomic, retain) NSString *requestId;
@end
 
@implementation ChildViewController
 
@synthesize requestId;
 
- (void)didReceiveEntityResponse:(EvriAPIResponse *)response {
  // TODO: hide the activity indicator
  // TODO: re-enable user interaction
 
  if ([response success]) {
    Entity *e = (Entity *)[success result];
	 // TODO: redisplay as necessary
  }
  else {
    // TODO: show an alert
  }
}
 
- (void)viewWillDisappear {
  [EvriApi cancelRequest:requestId];
}
 
@end

So there you have it, one developer’s way of integrating the iPhone with web APIs. More to come. Stay tuned.

I am pleased to announce the release of Peepcode’s latest screencast about MacRuby written by yours truly with Geoffrey Grossenbach and technical editing by Laurent Sansonetti.

Ever since I saw Laurent’s and Rich Kilmer’s presentations about MacRuby and HotCocoa at RubyConf ‘08, I’ve been jazzed about what MacRuby brings to the world of Cocoa development. So check out the screencast for the coolest new Ruby on the block.

This is the first in a series of posts I’ll be writing about my experiences developing the EvriVerse iPhone application for work. Since the end of 2008 I’ve been getting more and more into Cocoa for both the iPhone and Mac. The more I work on it, the more fun I have. I’ve got several side-projects in mind so I’ll be spending a lot more time in Cocoa-land and, as a result, blogging and tweeting about it a lot more.

I wanted to kick this off with a little appetizer. We’re going to look at how we implemented incremental find in EvriVerse. Evri has a huge database of structured entity data (people, places and things) and our users want to be able to search for any of them. After putting the initial prototype for EvriVerse on a few folks’ phones, a lot of them wanted a search feature that worked more like our website.

In the original implementation a user would type in the search field, then hit the “Search” button and then get their results back in the table view. This takes too many steps, and we wanted something that felt faster and more responsive.

So our incremental find solution needed the following properties:

• It should only send a search request when there is a measurable pause in input
• It should enable some kind of activity indicator while a search request is running
• A user should be able to modify the contents of the search field while a search request is in-progress
• It should not preclude the existing two-step search process
• If a search request is in process when another one starts, the first one should be cancelled and the new one should be the only request in-process

At first I tried managing my own NSThread instance while tracking the timestamps of touch events in the searchBar:textDidChange: method (part of the UISearchBarDelegate protocol). If the the gap between time samples was big enough I’d cancel any outstanding request and start a new one. This seemed like a good approach at the whiteboard, but really fell apart in the implementation. I had race-conditions left and right and I had the sneaking suspicion that I was swimming upstream against “the Cocoa way”.

As an aside, if there’s one thing I’ve learned in my brief time with Cocoa, it’s that mucking about with your own threads is a pretty crummy way to do things asynchronously. Usually there’s a much more elegant, built-in solution in the Cocoa APIs that will handle the threading for you. I’ll riff on this theme in a later post.

So back to the problem at hand. What to do? When I get stuck like this I often start thinking of how I’d do this in another language. This got me to thinking about how one would go about implementing this sort of thing in Javascript. This is standard Web-2.0 kind of stuff—right after drop-shadows and rounded corners, you learn about type-ahead search at AJAX School.

See, Javascript has this very nifty little function named setTimeout where you hand it a function and tell it how long you want to wait until that function is executed, and it returns you a reference identifier. There is a companion function, clearTimeout that allows you to cancel any previously-created “timeout” function by handing it the reference identifier you got earlier from setTimeout.

In the common AJAX-ified dynamic search that you often see, an event-handler observes the search field in a web form for key presses. Each key press cancels any existing timeout function, and starts a new one that will execute in whatever time-interval was chosen as the “quiescence period”. The trick is that because you’re scheduling future tasks, and you cancel any outstanding ones when you kick off a new one, you get the “measurable pause” feature in a simple, elegant solution.

Cocoa provides a very similar mechanism, through the NSTimer class. In my view-controller, the code ended up looking something like this:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56

@implementation FindViewController
// much implementation code has been elided for demonstration purposes
 
// observe text-field changes and fire the scheduled task
- (void)searchBar:(UISearchBar *)searchBar textDidChange:(NSString *)searchText {
  if ([searchText length] > 2) {
    if (timer) {
      [timer invalidate];
      self.timer = nil;
    }
    NSDictionary *info = [NSDictionary dictionaryWithObjectsAndKeys:searchText, 
                          @"Text", 
                          nil];
    self.timer = [NSTimer scheduledTimerWithTimeInterval:1
                                                  target:self
                                                selector:@selector(submitSearchRequest:)
                                                userInfo:info
                                                 repeats:NO];
  }
}
 
// The method that runs in the NSTimer--equivalent to the function 
// we'd pass to Javascript's "setTimeout" function
- (void)submitSearchRequest:(NSTimer *)aTimer {
  NSDictionary *info = [aTimer userInfo];
  NSString *text = [info objectForKey:@"Text"];
  [activityIndicator startAnimating];
  self.requestId = [EvriApi fetchEntitiesMatchingPrefix:text
                                        performSelector:@selector(didReceiveEntitiesDynamically:)
                                               onTarget:self];
}
 
// The callback from our API class, included for completeness
- (void)didReceiveEntitiesDynamically:(EvriApiResponse *)response {
  [timer invalidate];
  self.timer = nil;
  [activityIndicator stopAnimating];
  if ([response success]) {
    [entities removeAllObjects];
    [entities addObjectsFromArray:(NSArray *)[response responseObject]];
    [tableView reloadData];
  }
  else {
    UIAlertView *error = [[UIAlertView alloc] 
                          initWithTitle:@"Uh oh…"
                          message:@"Sorry, we were unable to execute your request. Please try again.
"
                          delegate:nil
                          cancelButtonTitle:@"OK"
                          otherButtonTitles:nil];
    [error show];
    [error release];
  }
}
 
@end

In the searchBar:textDidChange: method we check to see if our instance field, timer, points at an existing NSTimer instance. If it does we cancel it, clear the reference, and start a new timer instance. That timer is configured to run in one second and will execute our submitSearchRequest: method. This makes a call to our API and designates the didReceiveEntitiesDynamically: method as the callback for that asynchronous operation.

Finally, the didReceivedEntitiesDynamically: method handles the UI by disabling the wait indicator, dealing with any error cases and populating our table view if our request was successful. I’ll write another post later about how the EvriApi class works and its design.

So that’s it. Simple and elegant. One of the things I love about working on several different programming languages is figuring out how to apply the best tricks of one language to another.

That’s all for now, but stay tuned! More iPhone posts to come…

After several months of work, I’m pleased to announce the release of Evri’s EvriVerse for the iPhone. We’ve tried to capture the unique things we do at Evri into the awesomeness that is the iPhone. I won’t spill all the details here, so check out out the “official” company post.

I’ve been working on this thing for a few months, mostly on a part-time basis. We have a 20% time program at Evri where devs can pitch ideas they want to spend one day a week on. I was dying to write an iPhone app and jumped at the opportunity to turn it into a 20% project. After some early prototypes I got enough attention that I was given a solid two-week sprint to finish it off.

This was a ton of fun to work on and I have five or six posts on some things I discovered while working on it.

It’s free in the App Store now. We’d love to hear any feedback you may have, which you can post on the Evri Support Page.

One of the best ways to really learn the ins and outs of anything is to immerse yourself in all the gory details. Not only do you learn what works, what doesn’t, what’s elegant and what sucks, but you also start to grok the inner-workings. I just spent the last two weeks getting our own internal Git infrastructure up and running at work and I feel like Git and I have a new level of intimacy that we previously lacked. What follows is a review of the process and the solution that we’ve implemented.

For most of us at work, our primary Git experience is with GitHub. This is a good way to learn how Git’s distributed model works, but GitHub provides some nice infrastructure that you simply don’t have with a stock Git install. You have to cobble-together the rest from a variety of sources. So GitHub guys—if you’re listening—it would be fantastic if you provided real white-label GitHub solution for organizations to install locally. You guys have really spoiled us. (oops, nevermind. Checkout GitHub:fi). But until then, we have to roll our own…

The Goals

First, let’s review what exactly we were trying to accomplish. We wanted a solution that:

• easily converted existing Subversion repositories to Git
• provided a usable web view over all repos that was equal to, or exceeded, the stock SVN/DAV model
• allowed us to designate a set of “authoritative” repositories
• provided for “developer” repositories to allow developers to publish their changes
• allowed for patch reviews (if teams decide to do that)

The Solution

Right away we knew that we wanted two different types of repositories: authoritative and developer. Authoritative repos are ones that host the “official” source code and from which we create release builds from. When a developer wants to start working on a project, these are the repos they clone to get started.

The other type of repository belongs to an individual developer. Developers have read/write access to their own repos, but others only have read-only access. This allows developers to share changes in a pull-request model similar to how GitHub works.

Permissions & Connectivity

Developers connect to these repositories in two different ways. We use the built-in git:// protocol (with git-daemon) for read-only access and ssh:// for read-write access. Developers clone authoritative repos and other developers’ repos using the read-only git:// protocol. Developers have a remote reference to their developer repository using ssh.

For each project, we designated one or more maintainers that have write-access to the authoritative repositories. These folks accept patches from other developers, test and integrate them on their local machines, and push final changes to the authoritative repositories. We manage the authoritative repos using gitosis. Check out this great tutorial for details on setting up gitosis.

gitosis

On our central “git box” we create a “git” user which owns both the gitosis-admin repository as well as all the authoritative repositories. Gitosis is bootstrapped with a single SSH public key that gives the associated user the ability to write to that Git repo over SSH. That user can then add more keys and configuration allowing other users to manage projects. Gitosis works a bit like the CVSROOT project in CVS—it is a special Git repo that allows us to configure other Git repositories. We use gitosis to configure our designated maintainers for each project.

Our authoritative repos are housed in /home/git/repositories. Our developer repositories are located in /opt/repos, where each developer has their own directory to put Git repos in.

git daemon

We run git daemon to allow for anonymous read-only access. We configured git daemon to serve up all Git repositories found in the /opt/repos directory with read-only access. We also symlink the authoritative repositories (/home/git/repositories) into this directory so that we can serve up read-only access to authoritative repositories also.

gitweb

For all the power Git has, there sure are a lot of half-baked web interfaces for it. We did our best to vet the tools listed on the Git site. A good number of the them were either abandoned or simply didn’t work. In the end we went with the venerable old gitweb.

Gitweb has a ton of functionality—including all kinds of search capability, different views (by tag, by commit, by tree) and even serves up an Atom feed of changes—but it is definitely a designed-by-developers-for-developers. (NB: In case you missed the markup, that is considered an epithet on my team).

Frankly I was amazed that somebody hadn't built a Rails app to manage this stuff. Yes, we looked at gitorious and even tried to set it up. After three hours I still didn't have a working installation and my patience had run out. While gitorious appears to be a nice turn-key solution, I don't think it's actually that great of a fit for us. So gitweb it is. Sigh.

The Flow

With me so far? Maybe not. Let's look at a picture then…

In this picture the authoritative and developer repos are drawn in separate boxes (since they're logically separate), but they are located on the same machine in reality. Let's cover a couple of common scenarios:

New Developer, Old Project

A developer starts by cloning an authoritative repo using the git:// protocol (remember, read-only). This will create, by default, a remote reference named origin that points back to the authoritative repo.

The next step is for them to create a developer repo in their directory for the same project on the central git machine. They also want to a remote reference to their developer repo so that they can push changes to that. That would looks something like:

git remote add alex ssh://git/opt/repos/alex/circus/clown-car

If this user is also a maintainer, they need to add a third remote reference which gives them read/write access to the authoritative repository. The way that gitosis works is by accepting SSH keys on behalf of the git user. So if you're properly configured, you can push changes over SSH by logging in as the git user. A maintainer would add a read/write reference like so:

git remote add main ssh://git@git/home/git/repositories/circus/clown-car

Because of the way gitosis configures the SSH keys in /home/git/.ssh/authorized_keys and the fact that the default protocol is ssh, this remote reference could also be added like this:

git remote add main git@git:circus/clown-car

Now because there are number of steps involved here, we wrote a little command-line tool (as a RubyGem) that takes care of these steps all in one go. Right now, it's very specific to our setup at Evri, but I can see how we might extract a common tool (oh boy…another side-project…)
Old Developer, New Project
When it's time to create a new project, a developer usually starts out by creating a new Git repo on their local box while they're building out the initial version. Once it's time to share, that developer can create a new developer repo on our central Git machine just by SSH'ing in and making the appropriate directory, adding the remote ref to their local repo and pushing changes. Again, our internal tools sets this up all in one go.
Once that project is ready to have an authoritative repo, a gitosis-enabled user will pull the latest changes for the gitosis-admin project. They'll edit the gitosis.conf file to add the new project (and members) and commit the changes. Then the developer adds a new remote ref (a read/write one as the git user) and pushes changes out to the main repo.
Sharing Patches
The most common flow is when developers share patches with each other. There are a couple of ways to do it. Developers keep their developer repository up-to-date and email requests to their teammates to pull changes from their repo (a la GitHub). Developers may also choose to share patches via email using git format-patch, git send-mail and git am.
Ultimately the maintainers are responsible for gathering patches from developers and integrating them back into the authoritative repositories.

For folks used to version control systems like CVS or Subversion this feels like an awful lot of hoop-jumping. One part that I can't diagram or explain as a series of technical bullet-points is the stewardship the pro-Git folks have to take on. People who are switching to Git get frustrated by the byzantine nomenclature and steep learning curve, so a big part of the change and setup is simply helping people out when they get stuck.