How-to Change Standard Work Item Templates
This guide focuses on describing the practical change of the work item, starting from a process change request received, to the completion of a pull request updating the template.
Intended for
Configuration managers, software engineers, and anyone curious about the handling of template change requests.
Activities
Register a process change request
To register a change request for a standard work item template, the users should follow the How-to Create Process Change Requests guide and register the issue as a configuration management (CM) process issue.
The registered issues appear in the PCP R&D quality management system - configuration management backlog.
Review the change request
The CM process group is responsible for making decisions about the implementation of standard work item template updates. If needed, support from the ADO team could be utilized. The following should be considered:
- Is the proposed field/information of such value that it is appropriate in a template?
- Are there any conflicts with existing fields?
- What is a suitable field name?
After discussion within the CM process group, the issue is moved to either "Rejected" or "Active" state according to the "How-to Create Process Change Requests" guide.
If in the "Active" state, the issue is considered approved and assigned to one of the team members for implementation.
Update the template
The Configuration Management repo in ADO stores standardized templates used in ABB PCP, such as the standard work item templates.
Template updates should initially be validated in an ADO validation project, either on-premises or in the cloud, depending on the type of project. This is a learning environment where the change can be tested and demos can be done without updating the production environment.
- On-premises templates: Edit the template as XML and load it with Witadmin.
- Cloud templates: Edit directly from the "Organization" settings, "Boards-Process".
In both cases, templates must be stored in the Git repo and versioned.
When the validation project is tested, the required updates can be done in a branch in the Configuration Management repo in ADO.
A pull request is required to merge into the main branch. At least one team member must review and approve the change to complete the pull request.
Document and share
Use one or more of the following methods to inform users about changes in standard templates:
- Update the R&D process template guide (mandatory).
- Process demo.
- Presentation in the configuration management community meeting.
- Post in the configuration management channel.
Now the updated template is ready to be implemented in various projects. For further details, see How-to Adopt Standard Work Item Templates.
Details
Why templates are needed
In ADO, the projects contain different work item types (e.g. epics, features, or user stories) to track the work. Depending on the process implemented in the ADO project, different work item types can be implemented differently. Some typical cases are:
- Different field names.
- Different values for the same field (e.g. different states or bug severities).
- Different rules (e.g. who can change what, what values are allowed or mandatory based on other fields).
These differences make it difficult to have an overview of the status of releases, especially for systems that span multiple ADO projects. By using work item templates and thereby defining used work items and their fields, guidance is provided to the teams, and collaboration between projects is facilitated.
Where to find current templates
A description of work item types in use today and the fields that belong to their standard template can be found in the Azure DevOps area under "Tools and Templates". An ADO repo used for storing the templates can be found here: Opex - Repos - Configuration Management.