Skip to content

Work Items and Process Templates: Policies, Use Cases, Best Practices

Terms and definitions

Work Item - defines work that needs to be done for a project. There are various types and levels of work items.

Process - defines the building blocks of the work item tracking system and supports the Inheritance process model for Azure Boards. This model supports customization of projects through a WYSIWYG user interface.

Process template - defines the building blocks of the work item tracking system as well as other sub-systems you access through Azure Boards or an on-premises Azure DevOps Server or Team Foundation Server (TFS). It supports Hosted XML and On-premises XML process models which support customization of projects through the modification and import of XML definition files.

Process Template Guidance

The default process template for projects in the MDTProductDevelopment organization in Azure DevOps is based on the default Agile template authored by Microsoft with one addition, the Review work item type which is intended to track review work that is not able to be captured in code and in a pull request. This template will be applied to a majority of projects in the MDTProductDevelopment organization in Azure DevOps.

There is a project called shared which is intended to be the home for work that is applicable across projects, such as PXA (product portfolio, user experience, architecture). In this project we have added Initiative and Support work item types.

Support work items are based on a task work item type and should be used to allow teams to request work from other teams. Initiatives are parents to Epics. More information on both of these can be found below.

Note that this document does not cover Test Cases, Test Plans, Test Suites, Bugs or Issues but these do exist in both the default process and the shared process.

Work item types - definitions and use cases

The image below shows the hierarchy and relationships of work item types across various process templates available in Azure DevOps. ../../../Developer-Experience/img/MS-agile-process-workflow.png

Because our default process template is based on the Agile template from Microsoft the majority of work tracking involves Epics, Features, User Stories, Tasks, Issues, Bugs. Each of these work item types as well as Initiatives, Support, and Review work items are described in more detail below.

  • Initiatives
    • Note that this work item type is ONLY available in the shared project.
    • Parent to Epics
    • May cross team boundaries
    • Often requires multiple releases to complete, spanning over multiple quarters or even years
  • Epics
    • Large group of work that has one common objective
    • Exist at the portfolio level
    • Represent a business initiative
    • An Epic may span over many releases of software. It may never be truly completed.
    • Best practice in the default template is for an Epic to be the top-most item in a hierarchy with no other epics linked to it as a child.
    • Examples:
      • Increase customer engagement
      • Improve / simplify the user experience
      • Support mobile apps
      • Implement new architecture to support future growth
  • Features
    • Represents a shippable component of software
    • The Product Owner (PO) should work with stakeholders to define features based on Epics that have been created at the portfolio level.
    • A Feature is sized so that it can be completed in a software release.
    • The parent of a Feature is an Epic. The child of a Feature is usually a User Story.
    • Examples:
      • Support text alerts
      • Add mobile shopping cart
      • Refresh web portal with a new look and feel
  • User Stories
    • User Stories define the applications, requirements and elements that teams need to create.
    • POs typically create and prioritize User Stories with input from the team and based on input from stakeholders.
    • The parent of a User Story is usually a Feature.
    • User Stories should be scoped to be small enough so that it can be completed in one sprint.
    • A User Story should define who the Feature is for, what the user wants to do, and why this is important. It does not say how it will be implemented.
      • Example User Story: As a PO I need a way to predict when my product can release so that I can inform users and business stakeholders.
    • Acceptance criteria (AC) should be defined before work begins. This also helps guide the creation of test cases.
    • User Stories should be estimated with story points (not hours) so that team velocity can be tracked and release dates can be estimated. Best practices for estimating story points can be found here.
  • Tasks
    • Tasks are used primarily by teams using Scrum. For teams using Kanban, tasks are optional.
    • Tasks describe the work that has to be done (the 'how') to complete a User Story or resolve a Bug.
    • Typically Tasks are created by the dev team member(s) doing the work and have a parent-child relationship to map to the User Story or Bug that the work is for.
    • In Azure DevOps, the effort to complete tasks are estimated with hours according to the label. However, according to the Microsoft docs a team can use any measurement.
    • When a Task is a development (code writing) task, it should also link to a Pull Request (PR) that contains the code for the Task.
  • Bugs
    • Bugs are problems in existing functionality or missing functionality.
    • This could be a defect in code or requirement.
    • Bugs can be broken down into tasks if desired. This is decided within the team.
  • Issues
    • Issues are any event that could cause a delay in shipping a Feature or release a product increment.
    • Within the Agile base template Issues are basically an impediment.
    • Resolving an Issue requires more work beyond what is tracked for actual requirements.
  • Support
    • These are custom work item types based off of the Task work item type.
    • Support tickets are used by any team to request work of other teams
    • Should be regularly triaged by each team to determine how to handle the work requested (it may be more work than expected and require a new user story to be created or other further discussion between teams)

A quick note on the Review process. Currently we are engaging in discussions to determine the best way to handle this. In TFS teams used a Review tab, and we're currently evaluating the use of PRs and a Review Work Item type that could fulfill the Part 11 compliance requirements. More information about the Review process can be found in this publication.

Work Item States and Transitions

The image below is a nice illustration of the various state names and equivalents across the default process templates from Microsoft. ../../../Developer-Experience/img/work-item-states-across-templates.png

As a reminder we are using the Agile Process, so the states we will use are the following: MS-Agile-Process-States.png

Automatic state transitions can be accomplished as described in this repo. Some possible places where automated transitions could be considered: - If a task under a user story is active, the user story should be active. - When PR is created and linked to a task through a commit message, the task should be set to review. - When a PR that is linked to a task has been completed, the task should be set to resolved. - If all tasks under a user story are set to closed, the user story should be set to resolved. - Note that we automatically set things to active, review and resolved – NOT closed.

Best Practices

Attempt to understand the purpose of Agile work items before requesting customization. Every thing that is customized has repercussions for reporting, visualizations such as in Azure Boards and Kanbans, data roll-ups, etc, in addition to having to be maintained. If you are the only team that needs a customization you may be tasked with maintaining it.

As you do work and make decisions within Azure DevOps, use the discussion system. This way there is automatic documentation and communication of work being done and decisions that led to that work.

Use the link feature in the Azure DevOps work items to link to version controlled assets and other documentation. Create branches based on user stories or features, and link tasks in PRs. Read this publication for more information about source code and repo management.

As mentioned above, an Epic should be the top-most item in the work item hierarchy. It should have Features for children. In general parent-child relationships should not be of the same work item type.

Here is an image from Microsoft that illustrates linking work items to various other things in Azure DevOps: MS-Linking-Work-Items.png

Requesting customization to the supported process

Teams can request customizations that derive from and extend the existing process model. However, this should be done with great caution.

Typical requests:

  1. Custom fields, groups, and/or tabs. These requests will change the inherited process model and will affect the entire Azure DevOps organization. It is possible to limit the change to the project grouping within the org.
  2. Custom work item type. E.g., RPI work item type (WIT). RPI is a business process that needs to be captured and is used across the org.
  3. Show/hide fields. E.g., hide an unused state of a work item type.
  4. Change a field, tab, or group label or orientation. There could be times when renaming a label will make more sense depending on what data is captured.

All requests will begin with a support ticket. Along with what is being requested provide essential information:

  1. Why is it needed?
  2. How it will be used?
  3. And for the greater good: How will the CRM SW org benefit?

This request will require a review meeting to better understand the reasons behind the request. The meeting will include (at a minimum): Energizers PO, Energizers technical team representative, DevOps management team representative, requesting team PO, requesting team technical team representative

Possible outcomes of the meeting are the following: - Requesting team learns that the process can be used to fit their workflow. This may include using Tags or adding additional information to the title or contents of the work item. The query tool is very powerful and can be used to pull the information requested. - Default process should be changed for the organization. In this case the Energizers team is responsible for communicating the changes to the process and ensuring that reports and boards still work as intended. Note: the requesting team will have the opportunity to review the change prior to deployment. - In the last case scenario, the request may be deemed to be applicable only to the requesting team. In this case the requesting team would be responsible for the maintenance, interoperability and integration with reports of their process.

Why the inheritance process model?

Inheritance agrees with the SDA's simplification tenant. Adopting a simplified process model will reduce maintenance, reduce support costs, and more importantly, it will reduce differences in how projects develop software across CRM SW.

There are two process types in AzDO Services:

  1. Inheritance model (AzDO only) - GUI based and requires little overhead. Customizations are made through WYSIWYG UI.
  2. process template - XML template-based requiring tracking, testing, debugging, updating, and versioning. Allows for more customization options.
  3. on-prem (TFS)
  4. hosted (AzDO)

Inheritance was chosen for two reasons:

  1. Process templates on Azure DevOps [Services] require using Hosted XML. Hosted XML is an option only if the Microsoft data migration tool can validate our on-prem templates. Validation of on-prem templates is unlikely because of the extent of customizations to WITs and custom WITs have drifted the template far from the original template configuration.
  2. The Microsoft data migration tool requires a new/empty organization migration destination. Creating a fresh organization and migrating teams before being able to set it up goes against the SDA roadmap. This kind of migration may also introduce unwanted artifacts from the source to the destination.

Existing and supported customizations

This section will be updated to reflect a tabular view of AzDO supported customizations. Note: Custom WITs (E.g., RPI, Feature, Bug, and Requirement) were left out because of the large number of customizations.

References

  • https://docs.microsoft.com/en-us/azure/devops/boards/backlogs/define-features-epics?view=azure-devops&tabs=agile-process
  • https://www.freecodecamp.org/news/epics-are-dead-heres-what-we-should-do-instead-279bada1e644/
  • https://docs.microsoft.com/en-us/azure/devops/boards/work-items/guidance/agile-process-workflow?view=azure-devops
  • https://docs.microsoft.com/en-us/azure/devops/boards/backlogs/manage-issues-impediments?view=azure-devops
  • https://docs.microsoft.com/en-us/azure/devops/boards/backlogs/manage-bugs?view=azure-devops&tabs=new-web-form
  • https://docs.microsoft.com/en-us/azure/devops/boards/work-items/guidance/agile-process-workflow?view=azure-devops
  • https://yodiz.com/help/what-is-a-work-item/
  • https://blogs.incyclesoftware.com/modern-devops-practices-for-work-item-process-template-customizations
  • https://docs.microsoft.com/en-us/azure/devops/organizations/settings/work/customize-process-workflow?view=azure-devops
  • https://docs.microsoft.com/en-us/azure/devops/reference/process-templates/?view=azure-devops
  • https://docs.microsoft.com/en-us/azure/devops/organizations/settings/work/hosted-xml-process-model?view=azure-devops