[RFC] Workingstyle of different VCS systems

[Matthew Woehlke]

Andras Mantia wrote:
> On Thursday 05 April 2007, Andreas Pakulat wrote:
> [snip]
> My general feeling is that not all of the actions below need to be in 
> the interface. [snip]
> So those actions that are called only via the GUI by the user should not 
> have to be in the interface, they cam be provided by the VCS plugin 
> themselves.

Except this limits the ability to write scripts (or at least plug-ins) 
that can use arbitrary VCS back-ends. However the plan to use interfaces 
handles this, we have optional interfaces that need not be implemented, 
but provide consistent API's when available.

I just realized a potential issue; do we have a plan for how to go about 
splitting an interface without breaking the API/ABI if that should be 
needed? E.g. if we have an interface that provides foo and bar, and 
later want to implement a back-end for a VCS that only provides bar, 
what happens?

>> import - import a local dir into the VCS
> If we do not map the interface 1:1 to the VCS commands, I suggest to 
> merge this action with the "add" one. 

Yeah, this is just 'add directory recursively', don't see why it can't 
be combined into add. I'm not convinced we even need a recursive flag; 
if you add a directory, you get recursion (since only svn AFAIK supports 
versioning empty directories).

>> state - get the state of a local file, currently possible state flags
>> 	are:
>> 	Added, Uptodate, Modified, Conflict (between VCS-version and
>> 	local version), Sticky (some CVS thing, no idea what it means),
>> 	NeedsPatch (what does that mean?), NeedsCheckout, Directory,
>> 	Deleted, Replaced
> Maybe useful from a script, I don't see what you could do with this in a 
> plugin's code.

You don't use file tree, do you? :-) The state information is presented 
visibly in the file tree so you can see at a glance what files are in 
what state.

>> commit - let the VCS transfer local changes into the VCS
>> update - fetch latest changes from VCS into local dir
> This is normal to have, but IIRC ClearCase needs a lock before changing 
> the file, so maybe automatically lock before commit and unlock after it 
> (and remove th lock/unlock actions)?

lock/unlock are already going into a separate interface. Anyway, 
perforce is the same except the lock is done for you (probably svn is 
the same too, just less noisy). The way to handle this is to have the 
ClearCase back-end do the lock/unlock if that is required to do a 
commit; this qualifies as an Implementation Detail, which we are only 
concerned about when they dictate interface requirements.

>> log - Show a complete history for a given local resource or VCS
> I don't see why we need this in the interface, it should be enough to 
> have in the GUI.

I guess the objective is to not need a separate GUI 99% of the time. 
Anyway since the ideal is to be able to write an abstract GUI using 
these interfaces, we still need it in the interface. :-)

>> resource diff - show a difference between local file and latest VCS
>> version, or 2 VCS versions
> I don't really see a use case for this.

You've *never* done a diff? I do them all the time (like right before 
commits, especially). This so astounds me that I am certain there must 
be a miscommunication.

>> repositoryVersion - gives the latest version in the repository
>> localVersion - gives the version of the local file
> Use case?

Same as e.g. 'svn info', usually because the user "just wants to know". 
I feel it is a sufficiently standard action that it should be included.

>> merge - merges differences between 2 sources into the local file
> Merge is usually a complex operation which might require manual solving 
> of conflicts, further committing and such. Do we really need to expose 
> it to scripts/code?

Yes, because otherwise you have to leave KDevelop to do a merge. One 
objective is to avoid having to use external tools for common 
operations. (Note that resolve() is also in the interface.)

...but I've never heard of a merge requiring "further commits", usually 
the merge is something you do to generate changes withing the working 
copy, *then* you commit. Otherwise you are talking about non-atomic 
commits (ok, cvs is like this AFAIK) which are IMO broken. :-) Anyway, I 
don't see the problem.

>> revert - reverts local changes

D'oh, that reminds me... in perforce, there is also 'revert if 
unchanged' although really this is more like the opposite of edit(). The 
interface that has edit() should also have unedit() (or whatever name).

>> cleanup - fix inconsistencies with the local checkout
> 
> I saw a discussion about this. Cleanup in svn is something that I don't 
> remember to see in CVS or ClearCase. The perforce's 'sync -f', isn't 
> revert?

Yes and no, 'sync -f' means forcibly re-checkout *everything*, so it is 
a combination of revert everything and also check out anything you might 
have been missing, accidentally deleted, etc.

> Cleanup is something that should be hidden IMO, and probably having an 
> option to tell the plugins to "try to fix errors" and the Subversion 
> plugin should automatically run cleanup if needed (and the flag is 
> set).

We already agreed the "cleanup" won't make an interface, as it is too 
VCS-specific. :-)

>> copy - copy a file with VCS methods (history is kept)
> 
> You cannot copy with history in CVS...
> 
>> move - move/rename a file with VCS methods (history is kept)
> 
> Same here. I have the feeling that this copy/move shouldn't be in the 
> interface.

Not even via merge()? That's too bad, but IMO these should still have an 
interface (otherwise you *can't do them*, at least not without leaving 
KDevelop, and that would be unfortunate). They just won't preserve 
history on CVS.

I personally consider these to be core operations on par with add() that 
scripts should be able to rely on using.

>> info - Show some info of the local checkout
> 
> I think this is GUI only stuff.

Same comment as log.

>> mkdir - create a new directory in the local checkout and add it to
>> the VCS
> I suggest to use mkdir from KIO and add from the interface.

I think we either agreed to drop this or to implement it as KIO mkdir 
plus add(), since it really only applies to svn. Probably drop it (but 
provide a non-VCS mkdir in kdevelop), since either you will be adding 
files, or if you really only care about the directory (and are using 
svn), you can do non-VCS mkdir + VCS add by hand.

>> resolve - mark a conflicted file as resolved
> Belongs to the VCS plugin only.

I disagree, for the usual reason (no leaving KDevelop). Also if we have 
diff (*required* IMO) and merge, it would be stupid to not have resolve.

>> lock/unlock - lock a file or VCS resource
> I'm unsure if needed and if most vcs systems have it.

Already in an optional interface, as mentioned.

>> special - this should be available so clients may execute special
>>           actions for a specific VCS system
> 
> This might make sense, altough it is somewhat against the idea to hide 
> the VCS type. But to offer full power to the users, this is good to 
> have (together with a getVCSinfo to actually find out what VCS system 
> is used). Perforce's "integrate" could be a nice candidate to be 
> performed with this.

No, perforce's "integrate" is used to implement merge(), because that's 
what it does. :-)

We never really talked about this, but I don't think there should be an 
interface for "special". Individual back-ends can provide (outside the 
defined common interfaces) anything they feel useful. If that includes a 
TextEdit to allow executing arbitrary commands, that's fine.

> tagging was mentioned in the thread. It is probably worth to have. But 
> branching should (the actions can be different in VCS systems).

I forget what the consensus here was. In perforce, copy()/move(), 
merge() and branch() are all implemented by "p4 integrate", and then 
there is maybe tag() which is the same as branch() in svn but totally 
different in perforce.

> Regarding the need of an "edit" action before actual edit, this could be 
> done the following way: the framework could have a 
> signal "documentAboutToOpen" to which the VCS plugin listens and do 
> what is needed to allow the editing.

Nothing needs to be done on open AFAIK. However I think we need the edit 
interface because scripts probably won't open the file in the editor 
part in order to manipulate it. :-) And this means we should have 'unedit'.

> Similar signal could be 
> an "aboutToSave" or "documentSaved" which can be used to create scripts 
> that automatically commit your changes on save.

Huh? I do *NOT* want my changes committed when I save the file locally! 
That's not the way it usually works.

> This is weird, but 
> might make sense. This is a little OT for the thread, but we will need 
> such signals in other places as well to have the so called "event 
> actions" feature from Quanta (you can assign actions -execute 
> scripts/integrated actions, log the event, send email - to certain 
> events like those I wrote up there).

Hmm, be sure to add your weight to the discussion going on in 
kwrite-devel on this topic, then (you can CC here, I've been doing so on 
some of the posts but most respondents aren't). I didn't mention an 
onOpen signal as I didn't know of a need for one.

-- 
Matthew
GDRLaH - Grin, Duck, and Run Like a Hippo! :-)