Edgewall Software
Modify

Opened 19 years ago

Last modified 17 months ago

#1242 new enhancement

[ER] Generalized automatic cross-references in Trac

Reported by: Christian Boos Owned by:
Priority: normal Milestone: next-major-releases
Component: wiki system Version: 0.8
Severity: critical Keywords: xref
Cc: robert.pollak@…, emilk@…, nick+trac@…, martin.marcher@…, itamarost@…, olemis+trac@…, Ryan J Ollos Branch:
Release Notes:
API Changes:
Internal Changes:

Description

Problem

Trac provides a fast, easy and flexible way to relate Trac objects together, by the use of TracLinks in the WikiFormatting.

However, there's no automatic support for back-linking. This lack has been noticed in several circumstances:

  • BackLinks for Wiki pages (tickets #611 and #646, the latter containing a [http:/trac/ticket/646#change_4 note] which also highlights the genericity of the problem)
  • Related Changesets for a given Ticket (ticket #508)
  • Ticket dependencies and other relationships (tickets #31 and #226)

Instead, the backlinking is done manually. For example, when closing a ticket with a resolution of duplicate, the convention is to comment the closing of the ticket by saying this is a duplicate of #xyz and to mention the existence of the duplicate ticket on the original #xyz ticket. With a generalized backlinking facility, this would cease to be necessary.

Solution

What I would propose is that every relationship that gets detected while parsing new wiki content is recorded. Then, each wiki, changeset and ticket page could contain a See also: section at the end, listing the other objects that contain TracLinks targeting it, along with a bit of context, to catch the semantic of the link as well.


Example given:

Consider the following wiki OutstandingPatches page:

= Outstanding Patches page = 

I think that the patches #187, #909, #919, #944 and #948 are great!

Then, each time this page is edited, the content of an XREF (source, target, context table would be cleared for this page:

delete from XREF where source = 'wiki:OutstandingPatches'

and when the content is processed, each time a TracLink is detected, the table would be filled:

insert into XREF values ('wiki:OutstandingPatches',
                         'ticket:187',
                         'I think that the patches #187, #909, #919, #944 and #948 are great!')

Then, while browsing #187, one could easily get the backlinks:

select source, context from XREF where target='ticket:187'

in order to create the following output at the end of the ticket page:

Backlinks: OutstandingPatches

Of course, I'm willing to provide a patch for that, but I would like to get some feedback before.

— Christian

Attachments (1)

xref_cs1343.diff (59.6 KB ) - added by cboos@… 19 years ago.
The xref patch (on [1343])

Download all attachments as: .zip

Change History (22)

comment:1 by Christopher Lenz, 19 years ago

Yeah, this has been discussed before.

In the xref table, separate source type from source id, and context type from context id (would "dest" be a better name?), for quicker lookup:

CREATE TABLE xref (
    src_type    string,
    src_id	string,
    dest_type   string,
    dest_id     string,
    title       string
    relation    string
);

I've added a relation column here, which would be optional. This could be used for things like ticket dependencies. So you'd have both implicit backlinks (normal links in wiki text) and explicit relations (such as ticket dependencies) in the same table, which makes sense IMHO.

comment:2 by cboos@…, 19 years ago

Proposed Implementation

Features

Currently, cross-references between the following Trac objects are supported:

  • Wiki page
  • Ticket
  • Changeset
  • Report
  • Milestone
  • Source (only as targets for now)

Basically, two kinds of references are supported:

  • implicit references between objects
    Implicit references are created for every TracLinks that can be found in (any of) the wiki text of a Trac object. Indeed, some objects may have separately editable wiki texts, each of them being a facet of this object.
  • explicit relation between objects
    A relation must be created explicitely as such, by some programmatic mean. Currently, some of the ticket fields are setting up explicit relationships.

The user interface is quite consistent: for every page displaying an object which has backlinks, the first navigation link is Backlinks.

This goes to the /xref module, which displays the source objects in a way similar to the Timeline. First the relationships are presented, then the implicit links.

From that page, one can also navigate to the Forward Links (i.e. a summary of the outgoing links) and to the Orphaned Objects (i.e. those not referenced anywhere)

Consistency

The data model seems to be pretty solid, and the updates seem to work as expected.

How to install?

It is a clean patch made on the trunk as of today ([1343]).

It contains some database schema modification, so there is an upgrades/db10.py file.

So the recommended way to proceed is to use trac-admin, and:

  • upgrade
  • xref
  • resync

I left some 'print' statements on purpose, they should highlight what is going on when cross-references are created/deleted.

To be continued

This was really a very interesting task, I hope you will enjoy the results.

There are of course a few things that can be done from there:

Trac Objects

  • The patch is not very intrusive, it doesn't change the way the Trac internals work, but a very logical next step would be to program this in a more O-O way… which bring us in a very concrete way now in the direction of the TracObjectModelProposal (which will be re-edited shortly to reflect the experience gained while doing this patch)
  • In that framework, the xref trac-admin command will be able to handle relations (currently, relations only work for new tickets and modification of tickets, for the milestone and component fields)

Other things

  • A small change for the ticket comments was to introduce their numbering. This will also facilitate their editing (see #454). I also have some ideas for having threaded comments.
  • Some additional synonyms have been introduced:
    • issue is synonym to ticket
    • source, repos and browser are now also synonyms in URLs

by cboos@…, 19 years ago

Attachment: xref_cs1343.diff added

The xref patch (on [1343])

comment:3 by robert.pollak@…, 19 years ago

Cc: robert.pollak@… added

comment:4 by Florent Guillaume <fg@…>, 19 years ago

Cc: fg@… added

comment:5 by Christian Boos, 19 years ago

Milestone: 0.9
Owner: changed from Jonas Borgström to Christian Boos
Status: newassigned

A few informations about the future steps concerning the xref-branch:

  • have the feature integrated into the trunk, after my ticket category and intertrac branches are themselves integrated
  • add a time column in the xref table and sort the xrefs according to its age (the most recent first)
  • add a few more macros:
    • [[Backlinks]] that should provide a short list of implicit xrefs (i.e. not the relations, only the implicit references found in Wiki text); the display should match the original one suggested in the description for this ticket
    • [[Graph(relation_pattern,depth)]] which should provide a way to explore xrefs more than one level at a time…

comment:6 by anonymous, 19 years ago

Milestone: 0.91.0
Priority: normalhigh

As 0.9 is getting nearer, it seems I won't be able to finish it for that milestone. TracCrossReferences will be high priority for 1.0 though.

comment:7 by Christian Boos, 19 years ago

This feature is "alive", and quite in sync with the trunk.

The [[Backlinks]] macro mentioned above has been implemented in r2003.

comment:8 by Christian Boos, 18 years ago

Priority: highnormal

There are currently a few things of mine that are more ready for prime-time than this, so I'm lowering the prio.

comment:9 by Christian Boos, 18 years ago

Keywords: xref added

comment:10 by anonymous, 18 years ago

Cc: emilk@… added

comment:11 by anonymous, 18 years ago

Cc: fg@… removed

comment:12 by anonymous, 18 years ago

Cc: nick+trac@… added

comment:13 by anonymous, 17 years ago

Cc: martin.marcher@… added

comment:14 by Christian Boos, 16 years ago

Milestone: 1.0experimental

comment:15 by Christian Boos, 14 years ago

Milestone: experimentalnext-major-0.1X

Milestone experimental deleted

comment:16 by Christian Boos, 14 years ago

Component: generalwiki system
Severity: normalcritical

This ticket should be refocused on the cross refs part, as obtained by scanning resource links in the wiki. The "general relationship" management that was proposed in comment:1 will eventually be addressed separately (see TracDev/Proposals/TracRelations), but is out of scope.

comment:17 by Itamar Ostricher, 14 years ago

Cc: itamarost@… added

comment:18 by olemis+trac@…, 10 years ago

Cc: olemis+trac@… added

comment:19 by Ryan J Ollos, 9 years ago

Cc: Ryan J Ollos added

comment:20 by Ryan J Ollos, 9 years ago

Owner: Christian Boos removed
Status: assignednew

comment:21 by Ryan J Ollos, 9 years ago

Reporter: changed from cboos@… to Christian Boos

Modify Ticket

Change Properties
Set your email in Preferences
Action
as new The ticket will remain with no owner.
The ticket will be disowned.
as The resolution will be set. Next status will be 'closed'.
The owner will be changed from (none) to anonymous. Next status will be 'assigned'.

Add Comment


E-mail address and name can be saved in the Preferences .
 
Note: See TracTickets for help on using tickets.