$Id: OVERVIEW.txt,v 1.1.4.1 2008-12-10 23:43:48 jpetso Exp $

This is a short overview of the Version Control API (subsequently called
"the API") on a more conceptual level rather than detailed function
descriptions, as you've already got those in the module file itself.

The Version Control API module contains the central API and admin screens,
where the latter includes repository management, account management and
general settings.


User visible stuff
------------------

Repository management is very pluggable for both VCS backends and
external modules, so every module that needs to add some information
to repositories can do so. Repository settings at least include the name
and root path/URL of the repository, as well as a repository-specific
account registration message and URLs of external repository viewers
and/or issue trackers.

Furthermore, one of multiple authorization methods (also extensible by
other modules like Account Status) can be defined for each repository.
Version Control API itself provides two of them: 'none' which means that
every user with the 'use version control systems' permission can create
new accounts, and 'admin' which means that only administrators can
create any VCS accounts on the site.

Account management, in its vanilla form, is relatively bare-bone when compared
to repository options, and only shows a simple mapping of Drupal users
to VCS accounts, with a link to the edit account form on the user page.

General settings include the VCS admin email address and messages
shown on the account creation page.


API introduction
----------------

The API is a mixture of retrieving stuff from the database and delegating
to backend modules. It's extensively (some would say ridiculously) documented
with phpdoc compatible function descriptions, in order to make it very
straightforward for higher-level modules to use the API and for backends
to implement it.

For that matter, there also exists an example backend implementation called
"FakeVCS backend" which demonstrates how functions and their result data
might look like. This is a free-for-all especially for backend module authors
who can simply copy-and-paste apidox and function signatures into their own
backends and then use the demo code as a template for their implementations.
API users will probably gain a little more insight from the
hook_versioncontrol.module file which documents all the user-level hooks.


API concepts
------------

In essence, the API is built around various types of arrays
(think of them as objects) which can be retrieved and passed around:

- Repositories: contain fundamental information about the repository, like
    its name, root path/URL and the backend that powers this repository.

- Items: Files or directories inside a specific repository, including
    information about its path, type (file or directory) and (file-level)
    revision, if applicable.

- Labels: The combined representation of branches and tags, including
    the label type (branch or tag) and name (e.g. "trunk" or "DRUPAL-6--1-0").

- Accounts: Not represented as an array but rather as a combination of
    Drupal uid, VCS username and repository.

- Operations (commits, branch operations, tag operations): Those provide
    information about the author, repository, containing directory, and
    date/time of the operation. Where applicable, operations also include
    the repository-wide revision and the log message. Operations are also
    associated to the set of labels ("operation labels") and items
    ("operation items") that they modify/affect. When referenced from an
    operation, both labels and items feature a couple more properties, like
    the action that was performed on it in that operation.

Repositories and accounts can be extended by backends and other modules by
implementing the appropriate hooks (hook_versioncontrol_*(), where * is one of
'repository', 'account', and 'operation').

Each of those objects may contain additional VCS specific information -
for example, the CVS backend adds passwords to accounts, modules and
log retrieval information to repositories, and the commit branch to commits.
All in all, that makes for pretty good flexiblility.

A backend does not need to implement all functions that the Version Control API
defines. The idea is that functionality for retrieving fundamental
log information - that is, items and actions that correspond to commits and
branch/tag operations - is mandatory and likely to be stored in the database,
whereas more advanced functionality like directory/file contents,
file annotations, and listing all branches and tags of an item, is optional
for backends. That's because it's likely to directly interface to the VCS
instead of querying the database, and this functionality is both harder
to implement and potentially slower than the log retrieval functions.

If a user of the API makes use of an optional function then it has to check
for its availability before calling it.


So... that's it for the overview. Good luck!