Re: Shelfing

Stefan Kueng wrote on 2018-09-13:
> Hi Julian,
>
> Since svn 1.11 is soon to be released, I've switched my TSVN wc now to
> the svn 1.11.x branch. And apart from a few standard svn API's getting
> new versions (which won't be a problem to implement), the shelving API's
> have changed a lot. And I have now a hard time understanding them. I
> hope you can shed some light on them so I can understand and implement
> them correctly in TSVN.

Hi Stefan. I'm delighted to hear you are interested in updating shelving in TSVN.

I'm sure you are not the only person who finds the shelving APIs confusing, so I hope you don't mind me sharing this with the tsvn and svn dev lists.

The Wiki docs might be useful. This page in particular:
  https://cwiki.apache.org/confluence/display/SVN/Shelving+in+Svn-trunk

> oh, and why was the API renamed from shelve to shelf?
> And is it now 'shelfed' or still 'shelved' but one 'shelf'? Sorry my
> English isn't up to the task here, but I think it's the latter :)

One shelf, many shelves, and the action is to shelve, shelving, shelved. I decided the API naming worked better when based on an object (a "shelf") with actions applied to it (save, apply, unapply, list, drop, and so on).

> * what's the reason for having different versions of one shelf? I think
> I understand how the versions work, but I just can't see a use case for
> that. From my point of view, using only the latest version all the time
> would be enough. It seems this only makes the UI much more complicated?

Checkpointing ( https://issues.apache.org/jira/browse/SVN-3626 ) is enabled by allowing the user to save multiple versions of a shelf, and allowing the user to restore (unshelve) an older version.

The principle is that using shelf versions is equivalent to manually saving patches named "my-change-v1.patch", "my-change-v2.patch", ... and then when the user asks to unshelve "my-change" we give them the latest version by default or an older version if they specify it.

That said, I am already thinking a better API design would have a single-version shelf as its basic unit, and then an API to manage a series of versions with the same base name would be built on top of that basic unit. I filed an issue ( https://issues.apache.org/jira/browse/SVN-4748 ) about that.

> Also I still have no idea on how to implement that in the UI so users
> can understand it.

I sketched some suggestions for TortoiseSVN UI dialogues. They are attached to https://issues.apache.org/jira/browse/SVN-3626 .

> Also doesn't this increase the chance of conflicts if
> there are multiple versions of a shelf?

No, because each version is just like a stand-alone shelf. (The versions do not build on top of each other like revision records in a dumpfile do.)

> * what can make a path to get not shelved? Apart from the file not being
> modified?

A path cannot be shelved if it's copied or moved or is an added or deleted directory, or if it's in a non-committable state such as in conflict. The 'not_shelved_func' callback to svn_client_shelf_save_new_version3() is called in these cases.

> * do you think we should implement the versioning of shelves in TSVN?

Well... you don't have to. It's hard to tell how popular checkpointing might be until people try it. You could just implement unshelving to take the newest version, and not display anything about versions.

> I mean we'd have to use the log dialog as well here, and since a lot of
> commands that the log dialog now has implemented won't make sense for
> versioned shelves this requires also a lot of work in the log dialog.

> * what happens to all the other versions if a version of a shelf is
> restored?

If you just use svn_client_shelf_apply(), it just copies the changes in the specified version to the WC. All versions are kept in the shelf storage.

The command-line client's "svn unshelve ... VERSION" command deletes newer versions after successfully applying the specified version. That is because I was thinking of it as a "roll back" action. To implement that, the command-line client calls svn_client_shelf_delete_newer_versions(specified_version).

> I'll try to get most of the work done this weekend. So if you have any
> suggestions on how the UI/dialogs should look/work please tell me soon.

Thanks, and I would be very glad to hear more of your suggestions about how to improve the design.

-- 
- Julian