This thread follows on from the 'Artifact metadata and dependency management' thread - which was more about how to represent dependencies between resources in different repositories.
This thread will focus more on what additional information would be useful in this schema, related to the project lifecycle and methodology. This also ties into the documentation generation task, as the information can be used in any generated documentation.
We may need different levels of information, at the (1) project, (2) phase, (3) resource, (4) dependency, and (5) uri levels.
We could define some standard information in the 'tia' schema, but allow extensions that could be used in customised documentation generation templates.
(1) Project level, we need basic info, like project name and a description. Possibly something related to the stakeholders, and the project managers.
(2) Phase level, not sure whether this file should hold project management related information - but if so, then it might define timescales for delivery of a phase? It should atleast have a description, that can be used in the generated documentation for the phase.
(3) Resource level, will obviously want a description - so (for example) for a scenario, it should explain what the scenario represents. There should be information about the authors and contributors (people interviewed to obtain information used in the resource definition). If project management info is being recorded, then timelines could be defined - including review points and possibly signoff - with the details of the authorising party. Change history would also be required - this information could be used as part of a change management system later on, to track project/service revisions and how they impact (or are impacted by) other internal/external components.
(4) Dependency level, should have a description field. May want to define the action that should be taken if a dependency issue is detected(?). We may want some conditionality on the dependency(?)
(5) URI level - probably not much additional information is required, although the standard description should be allowed, possibly to explain why a particular location for the resource has been included.
A general issue will be how the information recorded in the tia is affected over revisions of the project and its artifacts. If review/signoff is recorded, then this needs to be tied to specific iterations. What information is explicitly recorded, and what information is subject to external version management.
Due to the varied locations in which this file may need to be used, it may be best to forget version management, other than as a way to track how the file contents changed over time. Therefore we need to consider how best to cater for project iterations and the impact it has on the information we record.
What should happen if there are two or more iterations occuring concurrently - i.e. a development branch, and a productisation branch. Should the same file be used to represent both, and the version information help to isolate which parts are specific to each version?
We need to consider some usecases, where issues may arise - for example, the simple case of adding new scenarios and updating the choreography to cater for these scenarios - this may cause dependency validation issues with service designs and implementations in the system being productised.
We could tag the new scenarios and choreography resource with a version - so when the validation is performed by the productisation team, these additional and changed resources are ignored. Or the productisation team could use a separate copy of the TIA project descriptor - but then what happens if they make changes, do these then just have to be merged back into the development streams version, as with other artifact changes?
I think my preference is that we treat the file as describing a particular version in time - and that version is declared as part of the (1) project level information. Each stream then works on its copy of the project file - but when appropriate, the development stream takes updates from the other stream(s). The only issue is what to do with signoff information, on resources that are changed as part of the subsequent work. Possibly the signoff information should be tied to the project version, but then each resource would also need to define which project version at which it was last changed.
But we need to explore other usecases which may not be as simple.