Add an example of using codebases

This ticket is a migrated Trac ticket [2945](http://trac.buildbot.net/ticket/2945)

People contributed to the original ticket: @sa2ajj, `benoit.allard@...`
Ticket created on: `Oct 15 2014`
Ticket last modified on: `Jan 15 2015`

---

While the notion is introduced and all relevant options are documented, it seems to be a good idea to add a separate example where codebases are used.

---

_Comment from_: @Ben
_Date_: `Oct 20 2014`

I could help there. Just need an example where it makes sense to use codebases: i.e. It is necessary to checkout multiple repository in order to run a command that need the outcome of each of them.

---
_Comment from_: @Ben
_Date_: `Oct 20 2014`

It's been suggested on IRC to add a picture about the conversion from changes to sourcestamps to buildset in the introduction chapter. I'll give it a shot.

---
_Comment from_: @sa2ajj
_Date_: `Nov 07 2014`

Based on the [[IRC discussion|http://irclogs.jackgrigg.com/irc.freenode.net/buildbot/2014-11-07#i_3490587]], a couple of different codebase mappings need to be shown and how they are handled by different schedulers should be explained.

---
_Comment from_: @sa2ajj
_Date_: `Jan 07 2015`

Things to cover:
* codebase generator
* scheduler configuration
* change filter
* use of codebase in build steps

Ben, an example where it makes sense is a two repo setup (e.g. lib + app) where we want to build both regardless of whether the change is coming to the lib repo or to the app repo. And in this scenario we'd like to build the revision for the change + master/stable of the other repo.

---
_Comment from_: @sa2ajj
_Date_: `Jan 15 2015`

One seemingly common use case: checkout two branches (of the same or different repositories) -- one according to the change, one according to the configuration. With the "default" configuration, both are checked out with the revision in the change, which causes errors.