Re: Version control support call for help

[Kai Willadsen <kai willadsen gmail com>]

On 12 June 2013 13:17, Louis des Landes <louis obsidian com au> wrote:
> <snip>
> > Oh, it's definitely followable. Your confusion is 100% warranted. I
> > think you're starting to see why I'm so scared of our VC subsystem.
> >
> > We don't have a documented API. Even if we *did* have an API, most of
> > these modules were created by someone copying another module and
> > munging things until they worked. So even if there was originally an
> > implicit API, it's long since died and we're left with a hunk of stuff
> > that mostly works but OH GOD DON'T TOUCH IT.
> >
> > So when I say that we should leave this stuff working the way it works
> > now and come up with a *completely new parallel API* that makes
> > sense... this is why.
>
> Fair enough. On that - given the process has started - where should it be
> documented? Docstrings? Still some work required if that's the case, even
> for the new stuff.
> I'll happily add some doco as I go, just not sure where exactly to put it.

Docstrings probably make the most sense I think.

Basically _vc should grow an actual API that gives us what we want in
VcView, and that we can try to follow consistently in the modules. We
need to be specific about what's passed in (e.g., are paths absolute?
relative to the cwd? relative to the repo root?), what we expect back
and what we use it for. Some of this will be fuzzy (e.g., revision
specifications will be VC-specific) but it shouldn't be that hard to
identify the information we actually want.

At this point, simplicity of VcView trumps simplicity of the VC
modules. If we have to add lots of calls to modules to make VcView
simpler, then that's the price we pay.

cheers,
Kai