Issues for TeamShare following alpha testing

1. Introduction

This is a list of all the open issues that TeamShare needs to look at and resolve, as of 2000-11-09, following alpha testing (see [RB 2000-11-04] for a summary of the alpha programme).

I have put the issues into categories by priority. The terms "critical", "essential", "optional" and "nice" are defined in [RB 2000-05-05, 2.2]. In particular, a critical issue is one which may cause the project to fail if it is not successfully resolved.

We need a commitment from TeamShare to a schedule to fix the critical and essential issues in time for the beta release in early December 2000. If TeamShare can't meet such a schedule, then we need to know as soon as possible so that we can work out what to do for the beta. We'd like TeamShare to schedule fixes for the essential issues in time for release 1.0 of P4DTI in February 2001. We need TeamShare to send us server builds as changes are made so that we have software to test against.

The intended readership is management and developers at TeamShare.

This document is not confidential.

2. Requirements that have reduced in importance

First, the good news. We found during the alpha test that some of our requirements were stated too strongly and some features of the integration are not as important as we thought early on. The following features in the TeamTrack interface are reduced in importance:

2.1. Filespec interface

None of the alpha testers were interested in associating filespecs with issues and certainly none of them were interested in editing them from TeamTrack. So all the features to do with filespecs are downgraded to Optional. This means that the project would still succeed even if no filespec interface were in TeamTrack. Users would still have the ability to associate filespecs with issues, since they can create a text field and enter them one per line. This could then be replicated with Perforce.

2.2. Editing and adding fixes from TeamTrack

Few of the alpha testers were interested in editing fixes from TeamTrack (everyone was interested in looking at them in TeamTrack). They wouldn't mind not being able to do it from TeamTrack because in practice what they will do is e-mail the developer concerned and tell them to put in the right fix information!

We don't have a requirement that people be able to do this, so the project would succeed if this feature were missing from TeamTrack.

3. Critical issues

3.1. There is no reliable way for the replicator to distinguish its changes to issues from changes made by other TeamTrack users

Currently the replicator looks at the "TS_USERID" field in the the "TS_CHANGES" table. If this is the P4DTI pseudo-user or 0 then it knows it doesn't have to replicate that entry. But Larry said that this is a bug in the API. In fact, the "TS_USERID" field in the "TS_CHANGES" table should contain the user on whose behalf the change was made.

We discussed a number of solutions to this issue at TeamShare on 2000-10-24. Since there is only one user field in the "TS_CHANGES" table, it is very hard for TeamTrack to record both the user who carried out the change (the P4DTI pseudo-user) and the user on whose behalf the change was made. John McGinley and Larry Fish said that they would think and come up with a solution.

See Ravenbrook's job000033.

3.2. Privileges can't be checked when updating an issue

The "TSServer::Transition" method takes an argument specifying the user on whose behalf the transition is being made. This allows TeamTrack to check the user's privileges. But the "TSServer::UpdateRecord" method doesn't take such an argument. So the user's privileges can't be checked and they can use the integration to get around workflow restrictions in TeamTrack.

We discussed this at TeamShare on 2000-10-24. Larry plans to add a method to the API which allows the API user to act as another user for subsequent operations (like setuid in Unix). We pointed out that you also need a method to return to the default state (acting as yourself). This should be satisfactory.

See Ravenbrook's job000038.

3.3. There's no design specifying how fixes and filespecs can be deleted from TeamTrack and the deletion replicated

I believe that the implementation is OK: deletions to fixes and filespecs show up as changes to the case in the "TS_CHANGES" table. This means that the replicator can spot the deletions and replicate them.

All we need is for what the API and server actually do to be documented. Then we can rely on it.

See Ravenbrook's job000032.

3.4. Changes made by TeamTrack aren't recorded in the "TS_CHANGES" table

When a case is transitioned, the "TS_OWNER" field may change (because of rules about who owns an issue at each stage in the workflow). However, this change is not recorded in the "TS_CHANGES" table. So the replicator can't notice the change, and so doesn't replicate it.

This has the effect that when a case is transitioned by the replicator (following a change in Perforce), the owner remains unchanged in Perforce even though it has changed in TeamTrack.

See [GDR 2000-10-31, item 4].

4. Essential issues

4.1. The fixes table is hard to read

The following improvements are required:

1. Borders around the table cells.

2. Give only the change number, the effect, the user and date for the change, and the change description. Omit the user, date and client for the fix, and the client for the change. (The omitted information can be discovered from Perforce.)

See [RB 2000-10-24, item 14].

4.2. The fixes table needs to have links to p4web

The change number in the fixes table should be a link to a URL on a server running p4web.

The replicator will record the URL for the p4web server for each Perforce server in its replicator configuration. TeamTrack can then build the links.

4.3. TeamShare API error reporting is inadequate

Most urgently, we need better error reporting when TeamTrack fails to carry out a Transition or UpdateRecord (insufficient privileges, missing required fields, transition not allowed, etc). These are the errors we need to show the user (by e-mailing the user who made the illegal change in Perforce) so we need errors that are suitable for presentation.

See Ravenbrook's job000006 and [GDR 2000-09-11].

4.4. What privileges does the replicator need?

The "Administrator" group might not exist at some sites. We need to figure out the recommended set of privileges for the replicator and instruct administrators to give the replicator those privileges explicitly.

See [GDR 2000-10-23, item 6].

4.5. The "Upgrade" installation option work when we installed 4402

We couldn't connect to the web server. So we tried the "Re-install" installation option and it worked. This is probably a bug in the 4402 installer.

See [GDR 2000-10-23, item 7].

4.6. How do we find out available transitions?

Workflows are different for different issue types, so different transitions are available for different issue types. But the "TSServer::ReadTransitionList" method only takes a projectid as its parameter. So the replicator can't accurately tell which transitions are valid for the case.

TeamShare need either to provide a way to accurately discover the available transitions for a case, or to confirm that this is a limitation so that we can document it.

See [RB 2000-10-24, item 25].

4.7. Change description not displayed properly

The change description isn't being correctly displayed in the fixes table at the bottom of the Version Control History section. In particular, descriptions with apostrophes in them aren't displayed correctly (the description stops just before the apostrophe), and descriptions with newlines are displayed with the newline appearing as "\012".

These are both symptoms of failing to parse the compound structures in the "TS_FILENAME" field in the "TS_VCACTIONS" table. TeamShare should ask if they are uncertain of what can appear here.

See [GDR 2000-11-03, item 6].

4.8. We would like TeamShare to provide free licences to P4DTI users (for the replicator)

This is really a policy decision for TeamShare management to make. We need to know what the decision is, and what the protocol for getting the licences is, so that we can document it.

See Ravenbrook's job000021.

4.9. What do we tell people about SourceBridge?

The integration won't work with SourceBridge. That is not a problem. However, in our user guide, we must tell people how to uninstall it. We also need to explain in the Administrator and User Guides how to achieve whatever SourceBridge achieved.

TeamShare need to confirm (a) how to uninstall SourceBridge (is the Add/Remove Program tool sufficient or are there any gotchas we need to worry about?) and (b) what are people using SourceBridge to achieve?

See [GDR 2000-10-23, item 1].

4.10. Generic copy

How can we stop the "P4DTI_" fields being copied when someone does a generic copy? These fields should go back to their default values when someone makes a copy of the issue. What do we put in the "TS_FIELDS" table so that this works correctly?

See [GDR 2000-10-27, item 11].

5. Optional issues

5.1. Checks based on version control relations

Several people asked if they could prevent a case going through some transition (e.g., Resolve) unless there was a changelist associated with it.

So it would be useful to have privileges and checks based on the version control relations.

See [GDR 2000-10-30, item 20].

6. Nice issues

6.1. If the case frame is too narrow, you lose transition buttons

When the frame is too narrow and there are more transition buttons that will fit in the width available, the ones that spill over onto a second row are half-hidden behind the ones on the first row. Seen in Internet Explorer.

See [GDR 2000-10-27, item 4].

6.2. Mysterious error in the TeamTrack event log

We saw a number of occurrences in the TeamTrack event log of the following error:

Exception occurred in file:
'D:\Reflex4.0.4\Db\AppRecordList.cpp', line 84.

    The record list with the 'select * from TS_VCACTIONS where TS_TYPE=3 and TS_INFO1 in (  )' select statement could not be read from the 'VCActions' table.

    Syntax error (missing operator) in query expression 'TS_TYPE=3 and TS_INFO1 in (  )'.

This looks like it's to do with the integration, but it's not a query from the replicator, as far as I know (I have looked at all calls to "TSServer::ReadRecordListWithWhere" in the replicator and none of them could have resulted in a query of this form).

6.3. TeamTrack looks like it doesn't actually read the "STATUS_VALUES" replicator configuration

We put some status values in the "STATUS_VALUES" replicator configuration, but the "Add Fix" and "Edit Fix" dialogs didn't have any values in the "Effect" drop down.

I've put this in the "Nice" section because we don't actually have a requirement for people to be able to edit or add fixes from TeamTrack (see section 2.2 above). But obviously if TeamShare go ahead with adding and editing fixes, then it is critical that it read the "STATUS_VALUES" configuration.

See [GDR 2000-10-27, item 10].

6.4. The VC Update Group isn't quite general enough

If TeamTrack is to offer adding and editing of fixes, then it would be nice if you could say "these people can edit the fixes but only when the case is in these states." That is, to have general privileges for editing version control relations.

I've put this in the "Nice" section because we don't actually have a requirement for people to be able to edit or add fixes from TeamTrack (see section 2.2 above).

See [GDR 2000-10-30, item 20].

A. References

B. Document History

Copyright © 2000 Ravenbrook Limited. This document is provided "as is", without any express or implied warranty. In no event will the authors be held liable for any damages arising from the use of this document. You may make and distribute verbatim copies of this document provided that you do not charge a fee for this document or for its distribution.