Version control plugin tutorial

Is there an overview of how to write a version control plugin somewhere?

I'm trying to follow the code for the git plugin, as suggested in the documentation, but finding it generally fairly incomprehensible - GitVcsSupport.buildPatch creates a GitPatchBuilderDispatcher, which builds a LowLevelPatcher, or possibly a GitPatchBuilder, which creates a VcsChangeTreeWalker which... well, I'm not really sure what it does.  This seems to be the general pattern of this code - it disappears down a rabiit hole that I'm sure makes sense when you know how it's all supposed to work, but is almost impossible to fathom when you're trying to pick it up from scratch.

Is there an explanation, or even a simple example, somewhere?

Regards,
Tom

7 comments
Comment actions Permalink

Hi Tom,

git-plugin is indeed quite complicated. It uses jgit library but due to memory problems we moved some of the operations into external process hence all this logic. It might be easier to understand mercurial plugin code (http://hg.jetbrains.org/hg/mercurial/), in particular how mercurial plugin builds patch from directory of files: http://hg.jetbrains.org/hg/mercurial/file/1f19b1a10edb/mercurial-server/src/jetbrains/buildServer/buildTriggers/vcs/mercurial/MercurialVcsSupport.java#l493. Basically all you need is to call the PatchBuilder.createBinaryFile() method with appropriate content and file path. Hope it helps.

BTW, what kind of plugin do you want to write?
0
Comment actions Permalink

Hi Dmitry,

Thanks for the pointer.  I'll have a bit of a look at the mercurial code and see if I can figure it out.

I'm interested in using Team Explorer Everywhere to create a version control plugin that can access a Team Foundation Server from Linux.  We have some code in TFS which we are trying to get building on Linux using TeamCity.  At present we are just using a command line build step to get the code out using the git-tf client, but think we could do better.

0
Comment actions Permalink

I have to say that, in the absence of any useable documentation on how version control plugins are supposed to work, I'm finding even the Mercurial plugin source extremely frustrating to try to understand.

Admittedly this is probably not entirely TeamCity's fault - it doesn't help that I've never used mercurial for anything beyond cloning an open source project off the internet.  But, trying to follow the source, I have dozens of questions which the source doesn't help to answer.  Such as, what is a mirror? What is a clone and how does it differ from a mirror? What is a clone of a mirror? What's a full patch and how does it differ from an incremental patch? If it's a full patch, it's not a patch, is it?  Isn't that just a copy of the repository at a particular rebision? What is an archive and how does it differ from a mirror or a clone? What does it mean to build a patch with or without an archive and when would either of them occur? What is a repository and how does it differ from an archive, a clone or a mirror? How is building a patch (buildPatch()) different to building an incremental patch or building a full patch? What is a work dir and how does it differ from a repository, a mirror, a clone or an archive?  How does the MercurialVcsSupport object even get created?  According to Eclipse, it has a single constructor which is only called by MercurialSupportBuilder.build, which is only called from test fixtures.  The documentation, so far as I can see, is completely silent on how a plugin is loaded and how TeamCity finds the relevant classes (if classes are what it needs) within it.

And why are there private functions with a single-line body that are only called once?  I mean, what is the point?  Frankly, quite a bit of this code seems to be taken from the "How to write unmaintainable code" playbook.

The point of all these questions is not to get tthem answered; the point is to show how difficult it is to figure out what function a version control plugin is supposed to perform given the near-complete lack of documentation.  Isn't there some documentation somewhere describing how it's all supposed to work?

0
Comment actions Permalink

Hmm, why couldn't you use a server-side checkout for TFS? If your server runs on windows it can talk to TFS, build a patch and send it to linux machine.

You mentioned git-tf, do you use git repositories in TFS? If so, then you can configure a git VCS root in TeamCity, it works both on linux and on windows.

0
Comment actions Permalink

You are right, writing a VCS support in TeamCity is not an easy task.. Unfortunatelly at the moment we don't have any tutorial on how to do that and all real-world plugins necessarily contain a lot of version control specifics which are completely alien to any other VCS plugin. Let's check if there is a workaround for your case so that you don't have to write a plugin yourself.

0
Comment actions Permalink

Yes, it looks like that is where we are heading.  It means setting up a Windows TeamCity server just to do the source control, of course.

0
Comment actions Permalink

If you can use git in TFS then the server can run on any OS

0

Please sign in to leave a comment.