Edgewall Software

Opened 11 years ago

Closed 10 years ago

Last modified 8 years ago

#3340 closed defect (fixed)

Node attributes 'created_rev' and 'created_path' not documented

Reported by: lewisbaker@… Owned by: Christian Boos
Priority: normal Milestone: 0.10
Component: version control Version: devel
Severity: minor Keywords: documentation
Release Notes:
API Changes:


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.

Attachments (0)

Change History (7)

comment:1 Changed 11 years ago by Christian Boos

Owner: changed from Christopher Lenz to 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

comment:2 Changed 11 years ago by Christian Boos

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

comment:3 Changed 11 years ago by 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?

comment:4 in reply to:  3 Changed 11 years ago by 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 ;)

comment:5 Changed 10 years ago by Christian Boos

Milestone: 0.10
Resolution: fixed
Status: newclosed

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.

comment:6 in reply to:  5 Changed 10 years ago by 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.

comment:7 Changed 8 years ago by Christian Boos

See also #7744.

Modify Ticket

Change Properties
Set your email in Preferences
as closed The owner will remain Christian Boos.
The resolution will be deleted. Next status will be 'reopened'.
to The owner will be changed from Christian Boos to the specified user.

Add Comment

E-mail address and name can be saved in the Preferences.

Note: See TracTickets for help on using tickets.