Arbit - project tracking

VCS module design

The VCS (version control system) module should offer an abstraction layer for various ways of managing source code and make it available for browsing with various optional annotations from the other modules.

Abstraction layer

The VCS abstraction layer is intended to offer access to the contents of directories and files managed in the respective VCS. Additionally, depending on the used VCS, metadata may be offered for files and directories, like a version history, version number, authors, etc.

Use cases

The abstraction layer is required to offer working abstraction for different types of VCS. For the inital implementation it should at least be tested against:

• Release tar balls

• SVN, as the classic central VCS

• Git, as a typical DVCS

The file data must be accessible by different means. For example the source code browser only needs to access information about selected directories and files. On the other hand source analysers or test frameworks need to have full access to the source in the file system.

Abstraction

The check is required to reside somewhere in the file system, so the root of the checkout can be passed to tools which require full access. These tools are required to itself take care of directories and files which are only relevant to the used VCS.

For the browsing interface and module annotations a full class orietated abstraction layer can be implemented.

Class interface

The two major elements of a file system abstraction layer are directories and files. For both base classes will be implemented, which offer access to the basic contents.

The implementations of these classes for a specific VCS may implement additional interfaces, which define the available metadata and offer access to the metadata. Such interfaces may be arbitSourceVersioned, or alike.

Serialization / Caching

Some of the metadata available for files may be expensive to fetch, like the log in SVN. Such information should be cached. The intuitive way of caching, serializing of the structs containing the data with var_export() should be replaceable by XML serialization to smoothly integrate with other tools, like PHP_Depend.

Module annotations

There are several ways of file annotations required by the various possible module types.

• Tree base annotations

  There might be code analysis (LOC, Costs, langauges) which are applied to complete subtrees / directories.

• File base annotations

  Source code analysers may want to add information to files (LOC, Comment ratio, ...)

• Line base annotations

  Testing frameworks like PHPUnit can generate line based code coverage information, which should be available in the interface, and can be added by line based annotations

• Character position based annotations

  Doc block analysers or code sniffer may be able to annotate words in some lines, which contain errnous / ... code.

Signals and slots for such annotations should be provided and cached by the VCS manager, because they might only be generated once for one revision of the respective source code.

Module signals

The module should emit signals for new revisions of files / subtrees, so that other modules may react on the changes in the source tree, for example by rerunning the test suite.

If the VCS support commit messages, the system should emit a signal containing the message, so that other modules may parse such messages and offer interaction based on that.