Edgewall Software
Modify

Opened 8 years ago

Closed 8 years ago

Last modified 5 years ago

#3340 closed defect (fixed)

Node attributes 'created_rev' and 'created_path' not documented

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

Description

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 8 years ago by cboos

  • Owner changed from cmlenz to cboos

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 8 years ago by cboos

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

comment:3 follow-up: Changed 8 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 8 years ago by cboos

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 follow-up: Changed 8 years ago by cboos

  • Milestone set to 0.10
  • Resolution set to fixed
  • Status changed from new to closed

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 8 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 5 years ago by cboos

See also #7744.

Modify Ticket

Change Properties
Set your email in Preferences
Action
as closed The owner will remain cboos.
The resolution will be deleted. Next status will be 'reopened'.
to The owner will be changed from cboos 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.