JSR-170 clarification - workspaces, branching, etc.

[Miro Walker <mi...@gmail.com>]

Hi,

Not sure if this is the right forum to be asking this - if not, please
could someone direct me to the right list?

I'm trying to get my head around the spec and I'm struggling to map
some of the concepts in the spec into real-world examples. Can someone
help? In particular, workspaces and branched version graphs are
confusing me. I think I may have it, but I want to make sure I'm not
misunderstanding....

For example, if one were to attempt to implement a source control
system such as subversion on top of jackrabbit, or any jsr-170
repository (has anyone done this?), then how would the concepts of
branches, tagged releases, etc. be implemented in a repository? I'll
try to write out what I understand, and if anyone could tell me where
I've misunderstood, I'd really appreciate it.

Tags, it appears would be implemented as version labels, so to tag the
current state of the entire content tree as belonging to a new
release, the base version of the content tree root node and every node
below it would have a new label applied to it for that release. To
retrieve this content, it would be necessary to traverse the content
tree, and for every node call getVersionByLabel on its version
history. Is that correct?

How about branching? What I'm looking for here is to be able to create
a new tree that includes all of the nodes in the original tree, where
by default each node "inherits" the state of its corresponding node in
the tree from which it was branched. Once a change is made to a node
in the branched tree, the version histories would diverge.

>From my understanding of the spec, this would be achieved by creating
a new workspace for the new branch (can this be done
programmatically?), then cloning or updating the root node of the
content tree into the new empty workspace (is there a difference in
this case between the behaviour of cloning and updating?). Each node
in the new workspace would then share the same version history as the
original workspace nodes, but the different workspaces would have
different base versions for that node, so when the node was modified
(a new version created) in the original workspace, this would not be
visible in the new workspace.

In order for the nodes in the new workspace to "inherit" the state of
the nodes in the original workspace, the node trees must be merged.
This would then cause the base version in the new workspace to be
updated to reflect the old workspace.

If, in the meantime, the node in the new workspace had been altered
(versioned), then there would be a branch in the version graph, and
the merge operation would fail for that node, allowing the application
to chosoe whether to keep them seperate or attempt to resolve the
conflict programmatically.

Is any of that lot correct? It seems like quite a lot would depend on
the efficiency of some of these operations (in particular, merge, as
it would need to be called every time a branched content set needed to
be viewed). How much have people used these features in anger? Are
there any examples out there?

Many thanks,

Miro

Re: JSR-170 clarification - workspaces, branching, etc.

[David Nuescheler <da...@gmail.com>]

hi miro,

> > > It seems like quite a lot would depend on
> > > the efficiency of some of these operations (in particular, merge, as
> > > it would need to be called every time a branched content set needed to
> > > be viewed).
> > really? i don't really see that.
> > for example, let's say you have a release 1.0 and a
> > release 2.0 of a piece of software in your repository then i
> > would probably assume a workspace per "release".
> > in my mind the merge() would only be called if a developer
> > patches release 1.0 and would also need to apply it to release
> > 2.0 on node that already experienced a check-in for 2.0?
> > in my mind that should not happen to frequently. please
> > apologize if i misunderstood your comment...
> So, if I understand correctly, without a merge being called, any
> patches made to the 1.0 worspace copy of a class (node) that had _not_
> been checked-in in the 2.0 workspace would not appear in the 2.0
> workspace...? 
that's correct, as long as no operation such as clone, update or merge
is called.

> This is what it appears to imply, as the base version of
> the node in question would be older in the 2.0 workspace than it would
> be in the 1.0 workspace, and only after merging would the 2.0
> workspace reflect the patch made in the 1.0 workspace. If that's
> correct, then it would appear the only way to tell by looking at the
> 2.0 workspace if a patch had been applied in the 1.0 workspace would
> be by calling merge()...?
hmm... i would argue that when the patch is applied to v1.0 the patch
should be checked-in therefore versioned, which then means that 
comparing the base version should do the trick, to find out that there
is a branch.
i guess from a versioning perspective in my experience we branch 
very often (once per release) and almost never merge, and personally
i don't really care what people do as long as it is not checked-in.

if i was in charge of the development guidlines on our fictitious example 
here i would probably postulate that every change on past releases 
should probably be checked-in as quickly as possible...

does that make sense? 

> > personally, i think that the "content explorer" usually helps quite bit
> > to wrap your head around the spec.
> 
> Content Explorer? I haven't found this - where is this? I couldn't see
> anything like this in the contrib directories... or am I being blind?

http://jsr170tools.day.com/crx/index.jsp

sorry, i forgot to mention that. it is our generic jsr-170 webgui... 
can be downloaded freely for development purposes or just be
used online for explanatory purposes.

regards,
david

Re: JSR-170 clarification - workspaces, branching, etc.

[Miro Walker <mi...@gmail.com>]

David,

Thanks very much for your reply. It sounds like I'm not too far off
track in my understanding... Couple of follow-up questions below:

> > It seems like quite a lot would depend on
> > the efficiency of some of these operations (in particular, merge, as
> > it would need to be called every time a branched content set needed to
> > be viewed).
> really? i don't really see that.
> for example, let's say you have a release 1.0 and a
> release 2.0 of a piece of software in your repository then i
> would probably assume a workspace per "release".
> in my mind the merge() would only be called if a developer
> patches release 1.0 and would also need to apply it to release
> 2.0 on node that already experienced a check-in for 2.0?
> 
> in my mind that should not happen to frequently. please
> apologize if i misunderstood your comment...

So, if I understand correctly, without a merge being called, any
patches made to the 1.0 worspace copy of a class (node) that had _not_
been checked-in in the 2.0 workspace would not appear in the 2.0
workspace...? This is what it appears to imply, as the base version of
the node in question would be older in the 2.0 workspace than it would
be in the 1.0 workspace, and only after merging would the 2.0
workspace reflect the patch made in the 1.0 workspace. If that's
correct, then it would appear the only way to tell by looking at the
2.0 workspace if a patch had been applied in the 1.0 workspace would
be by calling merge()...?

> i don't know whether in anger or not ;), but jackrabbit certainly
> implements all of the features and an example of
> a version graph can be found here:
> http://jsr170tools.day.com/crx/ui/versionbrowse.jsp?Path=/math.xml[3]
> 
> for manipulations you will have to login (admin/admin) here:
> http://jsr170tools.day.com/crx/login.jsp

Great - I'll have a look.

> 
> personally, i think that the "content explorer" usually helps quite bit
> to wrap your head around the spec.

Content Explorer? I haven't found this - where is this? I couldn't see
anything like this in the contrib directories... or am I being blind?

Thanks again,

Miro

Re: JSR-170 clarification - workspaces, branching, etc.

[David Nuescheler <da...@gmail.com>]

hi miro

thanks for your questions...

> Not sure if this is the right forum to be asking this - if not, please
> could someone direct me to the right list?
i think this is a good forum.

> Tags, it appears would be implemented as version labels, so to tag the
> current state of the entire content tree as belonging to a new
> release, the base version of the content tree root node and every node
> below it would have a new label applied to it for that release. To
> retrieve this content, it would be necessary to traverse the content
> tree, and for every node call getVersionByLabel on its version
> history. Is that correct?
yes

> How about branching? What I'm looking for here is to be able to create
> a new tree that includes all of the nodes in the original tree, where
> by default each node "inherits" the state of its corresponding node in
> the tree from which it was branched. Once a change is made to a node
> in the branched tree, the version histories would diverge.
> From my understanding of the spec, this would be achieved by creating
> a new workspace for the new branch (can this be done
> programmatically?), then cloning or updating the root node of the
> content tree into the new empty workspace (is there a difference in
> this case between the behaviour of cloning and updating?). Each node
> in the new workspace would then share the same version history as the
> original workspace nodes, but the different workspaces would have
> different base versions for that node, so when the node was modified
> (a new version created) in the original workspace, this would not be
> visible in the new workspace.
that's correct too...

the workspace management methods (create a new workspace, etc.) 
are available in jackrabbit, but have been excluded from jcr v1.0

it has to be said that you don't have to have multiple workspaces
to branch a version history, a restore and check-out for example
will do

> In order for the nodes in the new workspace to "inherit" the state of
> the nodes in the original workspace, the node trees must be merged.
> This would then cause the base version in the new workspace to be
> updated to reflect the old workspace.
> If, in the meantime, the node in the new workspace had been altered
> (versioned), then there would be a branch in the version graph, and
> the merge operation would fail for that node, allowing the application
> to chosoe whether to keep them seperate or attempt to resolve the
> conflict programmatically.
> 
> Is any of that lot correct? 
everything so far...

> It seems like quite a lot would depend on
> the efficiency of some of these operations (in particular, merge, as
> it would need to be called every time a branched content set needed to
> be viewed). 
really? i don't really see that.
for example, let's say you have a release 1.0 and a 
release 2.0 of a piece of software in your repository then i 
would probably assume a workspace per "release". 
in my mind the merge() would only be called if a developer 
patches release 1.0 and would also need to apply it to release
2.0 on node that already experienced a check-in for 2.0?

in my mind that should not happen to frequently. please
apologize if i misunderstood your comment...

> How much have people used these features in anger? Are
> there any examples out there?
i don't know whether in anger or not ;), but jackrabbit certainly
implements all of the features and an example of
a version graph can be found here:
http://jsr170tools.day.com/crx/ui/versionbrowse.jsp?Path=/math.xml[3]

for manipulations you will have to login (admin/admin) here:
http://jsr170tools.day.com/crx/login.jsp

personally, i think that the "content explorer" usually helps quite bit
to wrap your head around the spec.

regards,
david