Version Control API iterations

Well, I promised you an update on the API module, so that's what you'll get. Just a short notice beforehand: the CVS backend's database structure is now online and available for everyone's reviewing pleasure. Module functions will be added in a week or two, but before that, I'll get the xcvs-* scripts to fill in the entries for the new database structure. I've also made a (slightly different, but largely similar) SVN version of the .install file, you can find that one attached to this post. (As a Subversion backend module is only an optional deliverable, I'd rather not start a versioncontrol_svn project and its directory in CVS just yet.) So it seems to me that deliverable number three, a finished database schema for the CVS backend, can be marked as done.

Get to the point, dude!

Ok, ok. My remaining problem with the Version Control API was that it lacked a way to consistently deal with tags and branches, and to uniquely identify files and directories even if they are not versioned themselves (which is the case for directories in CVS and other version control systems). So I thought a bit more about how to deal with this, and the outcome is a new building block object for items, in addition to the previously existing ones for repositories and commits.

In the context of the Version Control API, items are file-level contents of a repository, that is, files and directories, whether they are versioned or not. The arrival of item arrays simplifies the API quite a bit, as items are now consistently used in function parameters and return values. You call some function and hand its items over to the next one as you need it, and that's a definitive improvement over the mostly correct but differently shaped return values that were in there before the rework.

The art of identification

Together with item objects comes the question of what is needed in order to uniquely identify such an item. I had quite a hard time thinking about this, and how would be possible to wrap it into the API in a nice way. The difficulty here is that there are a few special cases: items that are not versioned, items for which a repository-wide revision is given that doesn't match any of the file-level ones, items that you are retrieving from a certain branch or tag which you want to keep for the next function call.

What is then necessary to uniquely identify the most simple item object that doesn't fall under one of these special cases? Here's what I came up with:

• The repository.
• The path of the item inside the repository.
• And the file-level revision of the item, for example '1.2.2.7' in CVS or '127' in Subversion.

That's it. So an item array contains path, file-level revision, and item type that specifies if it's a file or a directory. The idea of the refactored API is to only pass around valid items that transparently encapsulate additional hidden info, like a tag or a global revision, without requiring the API user to know about all this stuff. For example, versioncontrol_get_item_branches() gets you a set of items in different branches, and passing one of these items (which is, say, a directory in the DRUPAL-5 branch) to versioncontrol_get_directory_contents() would automatically get you another set of child items from the same branch.

The same thing applies for view/diff URLs and the rest of the API. Which additional info is stored in an item object depends on the backend, so Subversion won't need to keep branches and tags in an item as there is no such thing in Subversion. (Internally, at least - it will nevertheless be possible to provide full tag/branch support by analyzing and transforming the item path.)

Upcoming work

I might just get the opportunity to continue my efforts so it seems appropriate to plan some more. My half-term survey for Google is filled in (and so is Andy's), the item stuff is figured out, and it's time to get my code to actually do some work now.

Supporting multiple branches in one project, especially if they can be maintained by different people than the actual project maintainer (yes, that's common in distributed development methodologies) is harder than I originally assumed. But as this would happen in the project node integration, it's also at the very top of the infrastructure hierarchy, so it can still be done afterwards without affecting the more low-level code. I talked to Andy yesterday, and he reminded me to stay down to earth and concentrate on getting the basic features to work, only afterwards worrying about optional extras.

And that's what I'll do. Luckily, that coincides with my schedule anyways, because that one says

Modify the xcvs-* scripts so that they store data in the newly defined database scheme.
Targeted for: 2007/07/19

Consequently, the plan is to

• Fill the database with commit info!
• Implement what's necessary to retrieve this commit info from the database!
• and: Display a commit log with all the info that has been retrieved!

Sounds like a good plan, doesn't it? When that stuff works, I'll get back to the more advanced stuff like account management, project node integration, motivation text approval, Subversion backend, Drupal-based repository viewer, world domination, ...yah, you get the idea. Make the functionality work that is used by and needed for drupal.org as it exists now, and afterwards add a whole lot of nice features that you did not ever think about in your nasty CVS restriction cage. And have a solid base for all of that.

Right now, I love doing this. You may have noticed.

Update: Inspired by aclight's comment, there's a new version of both versioncontrol_svn.install (attached, now as "v2") and versioncontrol_cvs.install (in CVS) that makes it possible to get the data for versioncontrol_get_commit_actions() only by querying {versioncontrol_[cvs,svn]_item_revisions}. Read the comments section for further information.