Traces and relationships

In a previous post I introduced a number of different types of relationships between artifacts in the repository, which go beyond the standard internet hyperlink. Here I’d like to explain a little more about relationships, to help you understand what they mean in the context of a corporate repository.

A hyperlink is a tag embedded in the text which instructs the browser to underline a portion of text and navigate to a specific URL when the reader clicks on that text. The browser is the sole interpreter working on your behalf. It reads in the page, figures out how to present the information to you, and follows the hyperlink when you tell it to. Only the page containing the hyperlink knows about that hyperlink – it’s not registered in some sort of central repository – so nobody else knows that the link exists. Well of course, that’s not really true, is it… Search engines build up their views of the internet based on the contents of those hyperlinks. This is one piece of information that they use to determine whether your site is a high-quality site or not:  More links generally means higher quality, means it gets higher on the list when the search engine presents its results to the user. Anyway, there are many programs that can search for hyperlinks on the internet. So if today I add a link to a bug I posted recently on JIRA in the Riftsaw project and the Riftsaw folks cared about such things, they could find out who is linking to them. Don’t know how to do that? Here’s something that will help.

But accessing an external web site to find out the information is a little too cumbersome to use inside a corporate repository. Instead, the repository should keep track of who’s pointing to whom. This is more than just having a foreign key reference inside a table. It’s a whole user interface built around the presence of the reference. In addition,

• often we need to keep track of not only the foreign key reference but also metadata around the reference such as suspect flags and histories; and
• bi-directional relationships allow you to go from A to B and also from B to A; and
• a given artifact A can point to B, C, D and E.

Therefore it’s probably best to construct your relationship tracker as a separate table, or indeed tables (for historical tracking), in your repository.

Why are relationships useful? For one, they allow you to discover things in your data that you might not otherwise discover.  For instance, if you see that twenty separate defect reports are related to the same Request For Change (RFC), then that tells you something about the urgency of the change request. The same RFC may be related to 3 different Projects but not the one you are currently working on, which tells you presumably that you’re going to have to suffer without the fix.

Traces are a special kind of relationship. You might find a trace between a test case and a requirement, as in “this test case verifies that requirement”. The difference between traces and generic relationships are in how carefully they are maintained and in the level of process associated with them. Traces are more “heavyweight”. You can’t just add a trace willy-nilly to a requirement. It has to be your job, for one. Second, when a trace is marked as suspect (because the artifact on the other end of the trace has been changed) then somebody has to go in and figure out what changed and whether the current object needs a corresponding update.

You can tell whether a relationship should be a trace by the nature of the artifacts on either end of the relationship. Certain artifacts – requirements, design specs, test cases, documentation – are what we might call “managed artifacts”. Analysts are assigned to work on them. In many respects, they are just like source files in computer programs. Relationships between managed artifacts are traces. Relationships between managed artifacts (on one end) and non-managed artifacts (on the other end) are simply relationships. And relationships between non-managed artifacts (on both ends) are also just relationships.

There are various categories of non-managed artifacts. I will talk about them in a future post.