TeamShare Alpha Test Meeting, 2000-10-23

1. Introduction

This is a record of a meeting between Richard Brooksby and Gareth Rees of Ravenbrook and Derek George of TeamShare on 2000-10-23. We discussed the goals of the alpha test, and configuration decisions for TeamShare PSG's use of the integration.

The readership of this document is the project staff.

This document is not confidential.

2. Alpha Test Goals

For Ravenbrook, the goals were requirements checking and discovery of missing requirements.

For TeamShare, the goal is to figure out how to provide services involving the integration.

3. Tasks and Roles

Manager

The person responsible for making the top-level configuration decisions like which cases to replicate.

Resolver

The person who receives e-mails from the replicator and resolves conflicts. Note that this is a decision maker, so needs to be a manager. (We need a better name for this.)

Process expert

The person who knows about and is responsible for development workflow (typically the engineering manager or the SQA manager).

Maintainer

The person responsible for keeping the integration running as workflows, users, projects, servers, resolvers and so on change.

Installer

[No definition in original source. RB 2000-11-20]

Configurer

The person who implements configuration decisions during installation and maintenance. Needs to be a programmer. Probably the same as the installer and maintainer, but maybe not.

4. Configuring the integration

These questions need to be answered:

1. What subset of projects do you want to replicate? Advice: answer "what do your developers need to see in Perforce?" and you should be able to figure this out.
2. What fields must you have to support the transitions you need? Advice: keep the minimum amount of stuff in Perforce.
3. How do states in TeamTrack map to states in Perforce? Advice: keep the set of states as small as possible at the Perforce end.
4. How do user names in TeamTrack correspond to user names in Perforce? Advice: use the same names in both systems if possible.

5. PSG's configuration decisions

Derek will be manager, installer, configurer, maintainer and resolver all at once.

PSG are doing one-time custom work. When they finish, all responsibility and maintenance are handed over to the customer. (Except that they guarantee that it will work with the next point release of the main software.)

Derek proposes four states, with the following transitions:

		NEW		IN WORK		IN TEST		CLOSED
NEW		--		work starts	--		--
IN WORK		--		--		to test		--
IN TEST		--		fail		--		deliver
CLOSED		reopen		--		--		--

Comments on this workflow: What about a RELEASED state? The CLOSED state should perhaps be DELIVERED (we propose that "closed" in Perforce not correspond to any TeamTrack state, so "closed" is a bad state name here). When you go to validation for a new release, is that a new state or the same as IN TEST?

Fields that PSG need in Perforce: project, description, title, owner, state, developer, tester, resolution summary, reason for failure.

6. Training in the integration

People will need training on using jobs. Use the p4 GUI where possible. (But note that you can't make fixes or interrogate the fixes relation in the Perforce GUI.)

A good approach to this training is to go through the use cases (see the user manual). There are four main ways of using jobs in Perforce:

1. Submit changes, then make fixes.
2. Make a pending change, make fixes, then submit.
3. Make fixes using the job form (not possible in Perforce 2000.1 unless the status of your fix is "closed").
4. Don't bother with fixes at all, just edit the jobs.

It would be a good idea to show people how to do exciting Perforce queries like "p4 fixes -j jobname" and "p4 jobs "//filespec@label". This would give a clear idea of what the integration is all about and what kinds of information we want to link together. Can all this be done in the Perforce GUI? If it can, we should show people how.

We should note that people are generally free to edit on the Perforce side, and this includes the freedom to make changes that would be illegal in TeamTrack. Explain what will happen when they do this. Explain the job of the resolver.

7. Things we need to do or remember in future alpha tests:

1. Ask senior management what their requirements are. They will interested in costs and benefit. How well supported will the integration be? How much will it cost to run and maintain?
2. Ask people to bring information to the initial meeting: namely the workflows, states and projects that they have in TeamTrack. Send an e-mail in advance.
3. People may have to modify their workflow at the point where they are deciding what fields and states should be stored in Perforce jobs. We should be prepared for this.
4. We will need a projector to tell people about the integration. We should at least have screenshots, or set it the integration on Virtual PC.

8. Issues Arising

These issues came up while RB and GDR were discussing the integration with Derek George of TeamShare:

1. Not enough data is replicated to TeamTrack for the TeamTrack interface to be able to offer users the equivalent of "p4 describe" or "p4 user". But we can provide an interface to that kind of information by making each entity in the fixes table in the case view in TeamTrack be a link to a web interface to Perforce that provides a description of that entity. Note that such a link mechanism needs to be able to support p4web, perfbrowse and possibly other web interfaces to Perforce.
2. There's a potential confusion between associated filespecs and filespecs associated via changelists. If a file is not submitted to Perforce, then it can't be associated using the filespec relation, since it has no filespec. Users of TeamTrack can use TeamTrack's attachment mechanism to attach the file. But if it is in Perforce then there will be changelists associated with that file that can be used to represent the relation. So do we need the associated filespecs at all? I think we should: the concept of "associated with a file" is different from "associated with a change to a file". So we should keep these things separate. But we need to make sure that the documentation helps people avoid this confusion.
3. The "Edit job" use case is missing from the original use cases document and hence from the user manual. It needs to be added to the latter.
4. We need to work out what happens to pending changelists when they're submitted? Are they deleted from Perforce? If so, we'll need to replicate their deletion.
5. Richard's proposed interface to fixes in the job form won't allow people to make a fix without changing the job status. But this kind of fix is very important.
6. How much Python experience does the administrator really need? (Our requirement 61 doesn't say). Someone who has general programming experience should be able to pick up Python quickly, so maybe we can express the requirement in terms of general experience.
7. We need to give advice to the person doing resolution of conflicts/exceptions. They need to do a good job. What advice can we give them?
8. At the moment there needs to be a state called "closed" in Perforce, because "p4 fix" without "-s" option sets the job status to "closed". Setting statusto "closed" can happen by accident, especially when a Perforce user has a jobview set. We can minimize the consequences of this by making sure that "closed" doesn't correspond to any state in TeamTrack, so that people who close jobs by accident in Perforce are found out when the replicator fails to replicate their change.
9. We should consider a default replication policy of "replicate when the case belongs to one of this list of projects."
10. A general policy for replication configuration: don't use database IDs to refer to TeamTrack entities. Use names. Reasons: when people change their workflows and states and so on, entities may get new IDs; database IDs aren't presented to users at any point in the TeamTrack interface. You'd have to go into the database with Access or Oracle or whatever, which is ugly. We need to advise people to try to use unique names for things where possible.
11. We discussed whether the replicator should replicate cases only when they're in a set of states when development activity is happening. But what would you do when the case was no longer in such a state? You can't delete it from Perforce because fixes refer to it. You can't even stop replicating because then queries in Perforce that referred to the job would be incorrect (remember requirement 1). What we might do is provide a feature for the replicator to mark the job as "not to be edited in Perforce" and to refuse to replicate changes back to TeamTrack until it's in a suitable state.
12. Ravenbrook should have a web page answering the question "Is this going to work for me?" This would explain hazards that would prevent the replication working, or which would make it excessively tricky. These might include: complicated workflows; undisciplined and frequent changes to defect tracking data.
13. We need a better name than "conflict", since they aren't always conflicts. Richard suggested "exceptions" but I don't like that.
14. Replication of PROJECT field is almost certainly always needed. We should provide a function to translate it.
15. An organization might require a fix or filespec to be associated with an issue before some transition is allowed. This can't be done in TeamTrack at the moment. But it would be useful if it could.
16. Might there be transitions that aren't allowed to be done in Perforce? Should the replicator provide this feature? Or could TeamTrack?

17. 17. The replicator should do some checking of the TeamTrack workflows when it starts up, looking for problematic cases. Three problematic cases are:

    1. two states with the same name in the same project
    2. two transitions between the same name
    3. two projects whose states have different meanings

    The configuration section of the administrator manual should include these problematic workflows as well (see figure 1).

18. A common conflict resolution policy for illegal transitions in TeamTrack will be to automatically set the Perforce job back to a copy of the TeamTrack issue and e-mail the offender (enclosing a copy of their illegal changes to the job). Is this even possible in the integration at present? We should make it possible, and we should provide implementations of policies like this that are likely be asked for.

Figure 1. TeamTrack workflows that P4DTI can't support

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.