Design Controls: Approvals with Azure DevOps

Overview

We are recommending that product development teams update their design plan with either a revision to the design plan or a DCR to the following process for design control approvals. At some point in the future we hope to have this incorporated into the official LDC processes that are impacted for software. The changes we are recommending in the following process are specific to an implementation in Azure DevOps for software development teams.

Process

The process for design control approvals will occur in Azure DevOps using a combination of two techniques – Pull Requests and Review work items. Pull Requests will be the primary vehicle for review of any asset that can be tracked by the version control system (repos within Azure DevOps). A Pull Request meets Part 11 compliance requirements for digital signatures and maintains a permanent immutable history of the reviews and approvals of work performed. It supports multiple signatures, comments on issues and their resolution and documentation of the work performed.

We assume that all people working with Azure DevOps are fully trained and understand the process of design controls, required approvals and their role on any work. When an individual signs a pull request they are signing it for an assumed role unless otherwise specified. They also understand the type of content associated with the pull request (e.g. code, verification, specification); therefore, their signature indicates one or more roles have been fulfilled. The following is the matrix of default signature roles based on work submitted.

The information contained in the following table is per design control processes as defined by CI TDC Product Development Process, DOC000689.

Review Work Item Type

For any work that does not follow this assumed approval role relationship or doesn't modify assets in azure devops repos that can be version controlled the review of the work will be performed with a custom work item called a "Review" work item. The review work item is a copy of the "Task" work item in the Azure DevOps Agile template with one additional change it contains a drop-down of all the LDC roles. User stories that require special or uncommon reviews will add a "Review" task to the story and assign it to the reviewer to perform the needed review. This additional "Review" task can be associated with a pull request if the custom review was related to version-controlled assets or just the story if not.

Pull Request Documentation

Good documentation practices are needed on pull requests as they are used as quality record reviews within Azure DevOps. It is possible to have more than one type of quality record in a single pull request. While this is uncommon it can happen and when it does it is important to provide the reviewers guidance on what they are reviewing. It is recommended inside the pull request to add an prominent section describing the quality records under review. The following is an example of that text for a pull request that contains both a specification and some software code.

Note: Contains Quality Records * Component Specifications * Software Code

Multiple reviewers per convention

If an LDC role calls out multiple reviewers for a quality record. You can @mention and tag the documentation for which role each user would be signing for but this should not be the norm. Only use this format of documentation if the LDC quality record has unclear reviewer roles per our convention. It would look like the following:

Note: Contains Quality Records * Component Specifications (@Bohannon, Kandyce as Verification Engineer Role, @Leska, Paul as Engineer Role Peer) * Software Code

If teams want to provide common review guidance in pull requests the Azure DevOps system provides a way to create pull request templates. These templates can have check-lists to provide guidance for their team members.

Reporting

The Energizers team has shown that we can build a report that lists all pull requests (PRs) in each project in an organization. That work is documented in this repo. For each PR, the report includes the work item that was linked to the commit, who reviewed it and when.

This report can be created and accessed by running the project's pipeline as described in the readme of the main repo. When the pipeline completes, the excel spreadsheet is published as an artifact that can be downloaded by anyone with access to that artifact feed.