Node attributes 'created_rev' and 'created_path' not documented

[lewisbaker@…]

The trac.versioncontrol.svn_fs.SubversionNode class defines the attributes created_rev and created_path here​. These created_* attributes are not mentioned anywhere in the trac.versioncontrol.api.Node interface class even though they are used in browser.py​ and changeset.py​.

I have been working on a plugin for another version control system and was wondering exactly what values I should be giving to these attributes.

They probably should be documented in the interface classes so that versioncontrol API users aren't using undocumented back door APIs.

[Christian Boos]

The semantic of created_path and created_rev were originally tied to the Subversion concepts of versioned trees of nodes. They were originally private fields, but I decided later to expose them and use them in the web_ui, partly because that was very convenient to address the need of showing the last change that happened on a node (see in particular r3099), partly because I came to think that this information could be meaningful for other backends as well.

So the created path,rev correspond to the path and revision at which a given Node was created. Conceptually, a Node is created when its corresponding content would change. For a Node representing a file, that would be a change to the file's content. For a Node representing a folder, that would be any change to a Node located below that Node. Additionaly, change to properties also trigger a creation of a new node.

So this is quite clear and simple, and I believe that this notion is at the heart of Trac's way to represent the content of a Repository, so you're right, it would be interesting to document it somewhere ;)

OTOH, it's the Node rev and path properties that are a bit more confusing. The rev property is made equal to the created_rev one, for "historical" reasons. But the path remains the path under which the Node is currently seen, which may not correspond to the created path (in case one of the parent Node has been copied). That was causing a few problems, and that's why I introduced the created_path field (and the created_rev for symmetry).

So my thinking was always to refactor the API to have:

• (rev,path) ⇒ the Node as currently seen and requested
• (created_rev, created_path) ⇒ the revision and path at which the Node got created (see above for when a Node gets created)

I'm planning to do that in the next bunch of changes for the versioncontrol layer, which hopefully will take place in 0.11 during the upcoming weeks (see VcRefactoring).

In the meantime, I'll try to summarize some of the above and put it in the doc, either for 0.10 or 0.10.1

[Christian Boos]

See unit-tests from r3493, which illustrate the above.

[lewisbaker@…]

That makes it clearer, thanks. :)

So am I understanding correctly in saying that if you have a file that was copied from /trunk/foo.txt@20 to /branch/foo.txt@30 and you construct a Node at /branch/foo.txt@40 and there are no changes to /branch/foo.txt between revisions 30 and 40 then path = '/branch/foo.txt', rev = 30, created_path = '/trunk/foo.txt' and created_rev = 20?

[Christian Boos]

No, the /branch/foo.txt path was effectively created at revision 30, since the /branch Node needs to be modified (it now contains a new entry foo.txt).

OTOH, if you copy /trunk@20 to /branch@30, then the Node for /branch/foo.txt@40 will be the way you described it above.

Hope this make it even clearer ;)

[Christian Boos]

As I don't think that part of the API will stay as is for long, I only documented it minimally, with a link back to here in r3572.

[Peter Dimov <peter.dimov@…>]

If only the create_* variables are ever used then just overwrite rev and path in __init__() of the derived Node class.

[Christian Boos]

See also #7744.