Welcome to QMS-ELSP | ELSP QMS Software

Protection of Development Environment

Mon, 01 Jan 0001 00:00:00 +0000

Purpose

To protect the product during development, implementation, testing and release as per ABB Cyber Security Standards and IEC62443.

ABB Cyber Security requirements this guide coveres:

ISA/IEC 62443-4-1 SM-7: Development Environment Security A process that includes procedural and technical controls shall be employed for protecting the product during development, production and delivery. This includes protecting the product or product update (patch) during design, implementation, testing and release.

ABB-SDLC-12 IT Infrastructure Security in software development All the Information Technology (IT) infrastructure, including but not limited to servers, virtual machines, working stations, cloud resources, regardless of who owns and maintains it, used for developing, building and deploying ABB software products shall be compliant with applicable ABB Information Security policies and standards.

Best practices

Use preferred ABB tools such as Azure DevOps, MS Teams, Windchill, Planisware etc. and apply least privileges when giving access to project members.
Create inventory of all IT assets ( template link) including all it assets used during the development e.g., workstations, laptops, cloud or local virtual machines, cloud subscriptions, docker containers, etc.
Apply ABB Information Security Policies and Standards for protection of all IT assets
Protect private keys and certificates from disclosure and unauthorized use
Use digital code signing for secure SW delivery to Factory, Supplier and Customers.

Example evidence for compliance with ISA/IEC 62443-4-1 and ABB SDLC

Development organizations can use this guidance as template to create project specific evidence

Usage of tools

Azure DevOps is used for planning, building, testing & deploying software. The cyber security of Azure DevOps is mainly managed by Microsoft and SOC report is Azure DevOps SOC Bridge letter (October 2024 – March 2025)

ABB DevOps administrators follow these Microsoft policies for managing access:
- Azure DevOps Data Protection Policy.
- Security groups, service accounts, and permissions reference for DevOps.
Internal project documents such as product architecture/design, user manual, test plan etc. are stored in MS Teams with restricted access to project members.
Windchill is being used for Engineering Changes of products in production

Usage of policies

ABB Code Signing process is applied to protect private keys and certificates disclosure or unauthorized use
Physical Security protection of IT assets are applied following ABB Policy: Link
MP 029 Engineering Change Notice (ECN) Process is followed to shared artifacts with ABB Factory/Suppliers.
Virtual machines are protected following Guideline for Using Virtual Machines on EndUser Devices
OPTIONAL: Any location specific policy. For example, Bergamo office have Operative Procedure PO 185/BG for managing the access of external personnel to the ABB premises.

Minimum needed by development teams

Inventory of IT assets but not limited to servers, virtual machines, working stations, cloud resources, regardless of who owns and maintains. Inventory Template: Link
Documented list of Configuration Management tools utilized by the development project (MS Teams, Azure DevOps, SharePoint, Planisware, Windchill etc.)

References

Security Development Life Cycle (SDLC) Standard

Scope

Mon, 01 Jan 0001 00:00:00 +0000

ELSP R&D Software QMS applies to all Agile Units of Smart Power Division. The QMS covers the product life cycles for development and maintenance of any software-based product offering in Smart Power Division. Software-based products includes embedded devices, software applications, mobile applications, web applications and cloud solutions.

Process Tailoring

Why do Process Tailoring?

Since different Agile Units require a different way of working e.g., coding guidelines and test frameworks.

What is in Scope for Process Tailoring

Policies and high-level processes are generally mandatory and not in scope (some processes can include variants, e.g., safety or not).
Guidelines and tools can be either mandatory or optional with various alternatives. The non-mandatory part is the main part of what is tailorable.
Tailoring often involves defining/adjusting activities, artifacts, and roles on a low level. Tailoring of tools can include tool selection or adjusting templates in an existing tool.

Roles involved in Process Tailoring

The tailoring will be initiated by experts in the Agile Units.
The Process Owner (PRO) shall be involved at least as a reviewer.
For Agile Unit tailoring the Agile Unit Leaders approves. This can also be delegated to relevant Chapter Leader.

Where to document the Process Tailoring

Long term, Agile Unit tailoring will be documented in local quality management system managed by the Agile Unit or local site, as a complement to the global QMS.
Short term, Agile Team documents any tailoring for the release.

Terms and Definitions

Mon, 01 Jan 0001 00:00:00 +0000

The table below lists and defines various terms used in this document or common conversations. It is collected here to make sure everybody understands them the same way.

Term	Definition
ADO	Azure DevOps
CoE	Center of Excellence
DoD	Definition of Done
DoR	Definition of Ready
DSAC	Device Security Assurance Center
NFR	Non-functional requirement
OCC	Open Source Competence Center
OSS	Open Source Software
PCR	Process Change Request
PM	Product Manager
PO	Product Owner
PRO	Process Owner
QBR	Quarterly Business Review
QMS	Quality Management System
RACI	Responsible, Accountable, Consulted, Informed
SDLC	Security Development Life Cycle
SM	Scrum Master
Software Composition Analysis	Sometimes known as Binary Code Analysis. An SCA tool makes an inventory of all open source components in the products and provides information such as the open source license and any security vulnerability associated with each component.

Threat Model Periodic Review

Mon, 01 Jan 0001 00:00:00 +0000

1. Purpose

The purpose of this document is to define a structured process for periodically reviewing and updating threat models for released products. Reviews should occur at least annually to maintain an effective security posture against evolving threats and to ensure compliance with industry standards and regulations. Reviews are recommended even when the product design remains unchanged, since the threat landscape may change over time, and also it is required by ABB SDLC and IEC62443 standards.

2. Responsibilities of Development Team

For a periodic review of Threat Model, the development team to ensure that the product remains secure as threat landscape evolves. Below are the key responsibilities of the development team during such reviews:

Review architectural changes
Validate existing threats
Identify new threats
Ensure that threat model is correct
Collaborate with security team
Implement and verify mitigations

3. Periodic Threat Model Review

3.1. Review Existing Threat Model

The development team of the product to check for:

☐ Last threat model and validate assumptions.

☐ Outdated mitigations

☐ New vulnerabilities in existing components

☐ Any addition of new 3rd party components

☐ Changes in threat actor capabilities

☐ Changes in product design & architecture

☐ Regulatory or compliance changes

3.2. Document and Communicate Update

The development team of the product to update the Threat modeling documentation with:

☐ Diagrams

☐ Threat Enumeration Sheet

☐ Share update with stakeholders

☐ Review record

3.3. Plan for Continuous Improvement

The development team of the product to plan for continuous improvement of the products with evolving threat landscape with

☐ Management of vulnerabilities in 3rd party components

☐ Schedule next Threat modeling review

4. References

Security Development Life Cycle (SDLC) Standard

Applicability

Mon, 01 Jan 0001 00:00:00 +0000

This procedure applies to all Agile Units (as development organizations) in the Smart Power Division that develop software or are involved in software development activities planned for release to customers. Agile Units must follow this process for the development of any kind of software, such as embedded products, software applications, web applications, and cloud solutions.

Cyber Security User Manual Template

Mon, 01 Jan 0001 00:00:00 +0000

User documentation (or user manual) should provide the necessary information to help the customer ensure that the product and the installed environment is as secure as possible.

The User documentation (or user manual) should contain relevant cyber security information for the product and also describe necessary additional actions that the user/customer/asset owner needs to take to install, commission, operating and decomission a product securely, and in general, to build the whole system or industrial plant following defense in depth approach expected my manufacturer.

Please use the template attached below to create product specific cyber security guidance for product user manual.

Cyber Security User Manual Template - Word file

Architecture Review Guideline

Mon, 01 Jan 0001 00:00:00 +0000

Architecture Review Goals

Evaluate the architecture early to avoid developing something that doesn’t fit.
Ensure consistency throughout the system. This will improve maintainability in the system and avoid duplication within the system.
Validate that the architecture builds a better understanding of the System Requirements, as well as identify any missing important system requirements.
Increase the overall knowledge of the product/system.
It’s important to formally document, and review, the architecture to comply with standards (ISO 9001, IEC 62443, IEC 61508, and others).
Ensure all documented architecture is also reviewed. If the architecture is worth documenting, it’s also worth reviewing it.

Architecture Review Checklist

When performing the architecture review, make sure to consider the following:

Is this content updated according to all relevant input requirements? Consider both specific functional or non-functional requirements and generic requirements e.g. requirements on architectural principles for security or other areas.
Is the described functionality following relevant input Architecture Specifications?
Are all major software/hardware components identified and their relevant interfaces defined?
Does the architecture specification have the right level of abstraction? The architecture specification shall provide an overview of and an introduction to the architecture using diagrams and textual descriptions on a high conceptual level.
Is the functional decomposition well described? For each functional element, there shall be a description of the provided functionality/service, the internal decomposition/structure, and the internal and external conceptual interfaces.
Is the dynamic behavior well described? Important concepts and functions shall have a description of their dynamic behavior on a high and conceptual level.
Is the information model described? The most important data entities relevant to the architecture, including their relationship, shall be described by the information model.
Is the deployment described? The deployment of functional elements into its execution environment shall be described.
Are architecture decisions described? The most important architectural decisions, including their motivations, shall be described.
Do all entities in the architecture have consistent names? All functional elements and conceptual interfaces shall have consistent naming. The same word shall have the same meaning throughout the description. Names shall be self-descriptive in terms of intent and behavior, and abbreviations shall be avoided.
Are sufficiently precise (i.e. sufficient quantity to be useful) descriptions put on:
- a) compatibility
- b) standard compliance (for example IEC 611131-3, IEC 62443, or OPC UA)
- c) availability
- d) configuration
- e) assumptions and dependencies
Is all mitigation of risks described in the threat model covered?
Is the architecture considering best practices?
Is the architecture feasible for refinement to a functional design (Description of Function)? Is the architecture described clearly and in detail?
Is the reuse of existing trusted and verified software modules/libraries considered?
If applicable, is the architecture structured so that reuse is possible for other components or products?

Template

Traceability is important throughout the entire development process. To simplify traceability for architectural review, use the template available in the Tools & Template translated into markdown format.

How to change the process

Mon, 01 Jan 0001 00:00:00 +0000

This guide takes you through the steps to initiate a change on the ELSP R&D QMS website by creating a process change request (PCR). It also includes information on how the process team handle submitted PCRs and updates to the QMS website.

A PCR can be created for improvements, missing information, or defects found in the processes, guidelines, etc.

Before creating a new PCR, discuss your improvement idea with your Chapter Leader. This helps to avoid duplicated PCRs and prevents unnecessary work.

Intended for

Anyone in ELSP who would like to file a change request for ELSP R&D processes must share and discuss the PCR with their Chapter Leader before submitting it.

Activities

Creating a PCR in Azure DevOps (ADO) requires an ADO license. If you don’t have one, ask the Process Owner for help creating the PCR.

Improvement ideas should be carefully evaluated and planned, with attention to their impact on other process areas within the QMS. Broader-scope improvement ideas should be managed as features, while individual, targeted changes can be tracked as PCRs. When multiple PCRs relate to the same area or topic, consolidating them under a single feature is highly recommended to simplify dependency management and enhance overall process coordination.

Create PCR

Go to the ELSP R&D PCR site to create a PCR.

Fill in PCR

The required fields in a PCR are:

Title A short description of the requested change.
Description Motivate change, origin, impacted document name/ID/revision, or tool template name with the problem statement and expected change. If the PCR is for withdrawal of wiki or QMS content, ensure that reference to any replacement is included in the PCR description.
Priority Select from 1-4 as per the definition. The priority (1=High… 4=Low) defines the order for the process team to handle the request. It can be redefined by the process team depending on capacity. See image here blow.
Due date Select an “expected due date” by the originator if the priority is 1 (immediate).
Affected standards Specify affected standard(s) like IEC61508, IEC62443, ISO9001.
Links or attachments Hyperlink the affected QMS document/page location and section, or attach the proposal/screenshots and other details.
Affected content type Hyperlink the affected QMS document/page location and section, or attach the proposal/screenshots and other details.
Reference CL The Chapter Leader with whom the change request was discussed, if applicable.

Submit PCR

Click on “Save” to submit your PCR.

PCR evaluation

The process owner evaluates the PCR and, if needed, contacts the originator to clarify missing information. After the evaluation it should be clear what actions to take to resolve the PCR.

PCRs across several process teams can be discussed in Chapters Committee (FW and Digital clusters) meetings. It may result in a split of the PCR for each process team.

State Change

Reason

Description

Mandatory fields

New

Moves to state New.

A new issue is found and logged by anyone.

Assigned to: PRO.

Title, description, hyperlinks.

Set "expected Due Date" and "priority".

1a, 1b, 3a

New to Closed/Rejected, Active to Rejected

Duplicate, rejected (edit reason manually).

PRO reviewed the PCR and found duplicate/invalid.

Assigned to: blank.

Edit the reason as "duplicate" or "rejected" manually

Link to other open issue work items before closing.

New to Active

Moved out of state "New" is considered as accepted/approved.

The PCR is approved for correction. This transition can take place once the PRO has validated the impact of the PCR. If necessary, the PRO will initiate a discussion with the CLs either in the comments section of the PCR, during the Chapter Community Cluster meeting, or through an ad hoc meeting. The outcome of the discussion will be documented in the PCR comments.

Assigned to: process owner.

Priority, stack rank, safety impact.

Discussion: using @ to notify additional members or with outcome of the meeting attached.

2a (optional)

New to Active

Investigate (edit reason manually).

The PCR is sent for investigation and assigned by the PRO to a specific stakeholder.

Assigned to: process owner or stakeholder.

Discussion: using @ to notify additional members.

2b (optional)

Active to New

Investigation complete (edit reason manually).

PCR moved back to state "New" by the PRO with the reason "investigation complete" to be processed.

Assigned to: PRO.

Hyperlink to impacted processes.

Committed due date, safety impact.

Set stack rank (within the backlog).

Active to Resolved

Moved to state "Resolved" is considered as fixed/ready for pilot.

PCR implementation complete/ready for pilot/training. Communicate to the originator.

Assigned to: process owner.

Hyperlink to changed processes.

Resolved to Active

Reactivated (edit reason manually).

Solution not meeting expectations of PRO.

Assigned to: PRO.

Discussion: using @ to notify additional members.

Resolved to Closed

Moved out of state "Resolved," it's considered validated.

PCR completed, solution met. Documents updated, pilots/training successful: the PRO can close it.

Assigned to: blank.

Closed to Active

Reactivated.

Closed by mistake.

Assigned to: PRO.

Discussion: using @ to notify additional members.

QMS website updates

The QMS website is made with Markdown files, versioned, and baselined. Pull requests in ADO are used to review and approve content before it is published on the web server. Content editing, reviewing, and approval are restricted to the process owner.

Review and Release

Procedure

The release of the MP028 procedure will take place semi-annually, unless urgent changes are required. All PCRs and features ready for release will be included in a candidate artifact.

Guide & Tools

Guidelines, best practices, and tool usage instructions will not follow a fixed release schedule. A candidate release artifact will be created whenever necessary—either when a sufficient number of changes have been collected or when urgent updates need to be implemented. These updates will be published directly within the QMS portal and will not be included in the PDF document.

Review

The implemented changes will be compiled and submitted for review to the Chapter Leaders. During this phase, Chapter Leaders must identify and report any issues within two weeks of the artifact’s creation. If no feedback is provided within this period, tacit approval will be assumed.

This review phase must be completed within two weeks, after which tacit approval will apply.

Approval

Approval of the process will be supported by AUL, CoE, and R&D managers. Once approved, the process will be published in the QMS and made available as a versioned PDF document. This phase also has a two-week timeframe, after which tacit approval will apply. This step is only applicable to procedure releases.

References

Azure DevOps site for PCRs PRO Sync

Area and Iteration Path

Mon, 01 Jan 0001 00:00:00 +0000

“Area Path” and “Iteration Path” are standard fields in Azure DevOps (ADO), and they are used to organize work items by product classification, team, and time period.

They both have a tree structure, and they are defined in “Project Settings”. They are covered in the online ADO documentation.

This guide focuses on how to use area and iteration paths in PCP.

Area path

An area path represents a functional area:

It can be a component/product and its version where applicable.
A team can be assigned to a specific area or a set of areas.

It’s possible to group work items in an area path, and to restrict access or to organize them in a logical structure. For example, the components developed in a stream are under the stream node, and can be grouped in an area path like this:

“Team Project\Stream\Product[\Major Product Version\Target Product Version]“,

where “Product” can be a tree structure of a main product type with several components. The sections within square brackets are optional and defined at product level. Depending on the convention used in the team, the optional parts may be used or not.

Examples of area paths:

PCP\Engineering\MyProduct\MyComponent\1.0
800xA Engineering and Production\Engineering\Eng Studio\6.0\6.0.0\6.0.0-3

An area path is usually set up by a configuration manager or a team project administrator. A product owner can request to be able to edit the areas of his/her product.

Iteration path

An iteration path represents a time interval and it is synchronized with increment planning, which gives a structure like this:

”Team Project\Stream[\Product]\Teams\Team Name\Increment\Sprint”

A concrete example of an iteration path is: “PCP\Operations\Teams\ATeam\24.1\24.1.3”

The configuration manager or scrum master administrates the sprints and selects sprints in the team configuration for the team to plan work items. Sprints and increments are managed according to the SPI calendar and synchronized with SPI planning. Bulk editing many iterations for many teams is possible using Azure CLI

Team configuration

Area path and iteration path are part of the Team Configuration in Azure DevOps

Teams can be defined for:

A virtual management team at the system or stream/project level, to monitor the backlog at that level.
An actual development team.

For each team, a backlog area and iteration are defined that identifies the scope of the team. Work items under the selected area/iteration appear in the team backlog.

In particular, the iteration up to the team’s name (PCP\Operations\Teams\TeamName) is the team’s backlog iteration, where the team keeps work items not planned for a specific iteration yet.

Area and iteration paths can be secured in “Project Settings” so that only authorized people can edit them.

It is possible to set permissions on area paths to restrict viewing or editing work items of each area.

Defining backlog levels

Backlog levels described in the QMS and mapped to SAFe Agile can be implemented by configuring teams with area path and iteration path.

Backlog level	Items	Area path example	Description
System	System epic	Area: <ADO Project Name>\PCP Work\System 800xA\7.0\7.0.0 Iteration: PCP\Operations\Teams\SystemManagementTeam\23.4	System epics imported from DFN and used as a basis for development.
Stream (or project)	Epic	Area: PCP\Engineering\NGT_Engg\CertificateDashboard\2.0\2.0.0 Iteration: PCP\Operations\Teams\ProjectManagementTeam\23.4	Epics planned for a version of a product/component.
Team	Feature User story (bug)	Area: PCP\Engineering\NGT_Engg\CertificateDashboard\2.0\2.0.0 Iteration: PCP/Engineering/Teams/TeamName/SPI/Sprint	Detailed work items that a development team plans and executes, to produce deliverables.

MP028

Wed, 11 Feb 2026 00:00:00 +0000

User-facing updates for the MP028 section. Newest entries come first.

Version: 1.0

Release: 2026-02-11

Summary

Initial revision.

Agile Team

Tue, 27 Aug 2024 16:26:15 +0000

The agile teams are focusing on the development of Software (SW) components. These components are integrated into products and released to customers.

The agile teams focus on lean‑agile planning and execution.

The teams use iterations (or sprints) to plan, implement and deliver SW solutions.

Process Overview

The iteration (or sprint) planning and execution of the agile team follow lean and agile principles. Each increment starts with a Quarterly Business Review (QBR), followed by synchronization events, and ends with an inspect & adapt (retrospective).

Principles

Ensure the team backlog is ranked.
Plan the iteration/sprint.
Visualize work.
Coordinate at daily stand-up meetings.
Demonstrate value.
Improve the development process.
Build quality in.
Ensure adherence to DoR and DoD.

Activities

Artifacts

Artifact

Description

RACI

Receiver

Tailoring

Iteration Goal

Summary of business and technical goals for the iteration that the agile team agrees to accomplish.

R	Agile Team
A	Scrum Master
C	-
I	-

Agile Team

Team Board

Visualize the status of Agile team progress, physical or digital board

R	Agile Team
A	Scrum Master
C	-
I	-

Agile Team

Story

A (user) story is estimated and ranked in this process. For details about contents, see the "requirements" process

R	Agile Team
A	Scrum Master
C	-
I	-

Agile Team

Task

Piece of estimated work (hours) for a team member. It is a work item in Azure DevOps.

R	Agile Team
A	Scrum Master
C	-
I	-

Scrum Master

Team Backlog

Contains estimated and ranked stories and enablers originating from products backlog and additional stories from the team's local context.

R	Agile Team
A	Product Owner
C	-
I	-

Agile Team

Impediment

Anything that keeps the team from getting work down or slows velocity. Identify in Daily Stand-Up.

R	Agile Team
A	Scrum Master
C	-
I	-

Agile Team

Risk

Can cause future problems, loss, or threaten progress but has not happened yet.

R	Agile Team
A	Scrum Master
C	-
I	-

Agile Team

Details

The agile team process focuses on lean-agile planning and execution. The process ensures the teams plan, execute and deliver according to expectations. The agile teams are aligned to the increments by the QBR.

Master Processes

The agile team process belongs to the “master processes” responsible for continuous planning and execution. It takes the required activities defined in the functional processes (e.g., requirements, architecture, and test) and adds them to the iterations.

The Agile teams can use Scrum. Irrespective of the agile method, the team needs to sync to the common cadence in the Agile Team. Deliverables and demos need to be prepared by the team.

Cadence view

The cadence view shows the process activities and the increments. Many of the activities are executed in parallel and not always in a sequence.

The team’s cadence is aligned to fit into the QBR increments. The iterations are, in most cases, 2 weeks, but they can be longer as long as they fit into the increments.

Flow view

This view shows an overview of one iteration (2-3 weeks).

The flow view shows the process activities and the logical sequence with decision points. It makes it easier to understand the flow and the relationship between the activities.

Definition of Ready and Definition of Done Scrum

How-to Change Standard Work Item Templates

Mon, 01 Jan 0001 00:00:00 +0000

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 Change the Process 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.

Use one or more of the following methods to inform users about changes in standard templates:

Update the QMS 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” in the QMS. An ADO repo used for storing the templates can be found here: Opex - Repos - Configuration Management.

References

How-to Adopt Standard Work Item Templates Configuration Management repo in ADO How-to Change the Process

Guides

Thu, 12 Feb 2026 00:00:00 +0000

User-facing updates for the Guides section. Newest entries come first.

Ver: 1.0.1 Rel: 2026-02-12

Summary

Folder restructuring and new guide sections added to organize content more effectively.

Changed

Reorganized guide folder structure for improved navigation and content hierarchy.
Updated menu reference for procedure change process documentation.

Added

New guide sections on team updates, contribution flow, and related best practices.
Expanded introductory content with getting started sections in multiple guide areas.

Ver: 1.0.0 Rel: 2025-11-05

Summary

First release.

How-to Manage Bugs

Mon, 01 Jan 0001 00:00:00 +0000

A bug is an unexpected problem in the software or hardware which can be reported for any issue in a product by e.g. product managers, product owners, test engineers, or customers (via L3 or L4 Support).

Managing bugs is a complex task, offering many options depending on the nature of the bugs. This guide describes the overall bug management process, and links to other bug-related guides as visualized below.

This means that – when creating a bug – it’s important to:

Classify the bug.
Know if it is a “usual” bug, an enhancement bug, a regression bug, or a bug existing in multiple releases.

Intended for

Release owners, product owners, scrum masters, software engineers, hardware engineers, test engineers, and L4 engineers.

Activities

Create bug

A bug work item in Azure DevOps (ADO) captures the problem in a way that can be communicated and corrected. The goal of creating a bug is to accurately report a problem in a way that allows the reader to understand its full impact and background. For how to set the severity, security effect, and priority of a bug, see the Bug Classification guide.

If the problem is already reported by another bug, the duplicate one must be closed and linked to the already existing one.

Bugs are created for defects found in completed work items. Under some circumstances it is possible to handle enhancements as bugs, see How-to Handle Enhancements.

Regression bugs should be marked and handled according to Regression Bugs.

Each bug must describe one specific problem:

If more than one problem is found, more than one bug must be entered in ADO.
If the bug impacts several function areas or product lines, then clone the bug to each impacted area.
If the bug affects more than one release, see How-to Handle Bugs in Multiple Releases.

When creating a bug, refer to Standard Bug Template and Area and Iteration Paths for mandatory fields to fill in.

Note: The assigned area path, which identifies the product or version where the issue was found, should never be changed. If it’s necessary to assign the bug to a different area path, please follow the process for deferred bugs, see How-to Handle Deferred Bugs.

Check DoR

All available information must be clearly described in the bug work item’s mandatory data.

Bugs related to specific work items (e.g., features, user stories, etc.) must be linked with the work item itself.

The new bug is assigned to the product owner or the scrum master.

The product owner or the scrum master verifies that the definition of ready (DoR) is met.

CCB decision

The change control board (CCB) decides if the bug shall be fixed or not, and whether it should be accepted for the current release or assigned to a future release. If a bug is not properly assigned, the CCB is responsible for making sure that the bug is correctly addressed. See State and transitions for further details.

CCB involvement is strictly required for post-release bugs including L4 bugs and their definition of done (DoD), see DoD for L4 bugs. CCB decisions must be recorded appropriately.

Note: Product owners, release owners, and scrum masters - if they are also part of the CCB - can close anything within the scope of the CCB group, including bugs, using the recommended best practices and the “4 eyes rule”. They can also decide the priority of the introduced bugs, and are expected to take decisions within two weeks and to finalize (close) the bugs in two sprints.

The goal is to have virtual zero test (introduced) bugs by the end of the sprint. If any bugs slip to the next sprint, they must be prioritized by the development team and fixed. All possible reasons for closure are accepted as long as they are documented.

Changes in the project’s scope and decisions on what bugs shall be included in a specific release can only be done by the CCB.

Only product owners or the CCB can change the severity. The reason must be documented, and the bug author must be notified.

Bugs that impact safety, security, or multiple teams must be escalated to the CCB. CCB approval is also required to defer introduced bugs to future releases, see How-to Handle Deferred Bugs.

Investigate

Impact analysis must be done for every new bug: which requirements and/or functions need to be re-tested, which documents need to be updated, and the impacts on other parts of the system must be evaluated and described; impact analysis needs to be tailored to the stream needs.

The standard impact analysis template for bug consists of 5 questions:

No.	Question	Explanation
1	What is affected?	Please identify the specific product name, version, and components that are impacted by the change or issue.
2	How is it affected?	Analyze the nature and extent of the impact on the identified areas. Consider how general system functions, performance, properties, and libraries are affected by the change.
3	What is the solution and how long will it take?	Propose viable solutions to fix the issue. This may involve technical fixes, process adjustments, or resource allocation. Estimate the time required to implement the proposed solutions, considering the complexity and resources needed.
4	What needs to be changed?	Clearly define the changes required to address the impact. This includes modifications to design and documents including user documentation and security documentation. For document please list the document ID, title and version. For code please list the code file name in repository.
5	What tests need to be executed?	Please list here the required test cases to be executed, including test cases to be rerun and/or new test cases to be developed, to ensure the bug is fixed without introducing new issues, e.g. regression testing related to security for changes to security critical components.

For bugs in Functional Safety related releases (interference free included), please use IA Questions for Error Corrections: 3BSE042623 and IA Guidance Safety - 3BSE058012.

Security analysis must be completed for every new bug, and critical issues are discussed with the cyber security engineer.

Investigation information, such as impact analysis, CCB decisions, implementation proposals, and other critical details, must not be shared in the “Discussion” field since it will be lost if a bug is cloned. Instead such information can be stored in other fields such as “System Info”, “Description”, “CCB Discussion”, “Impact Analysis”, or “Workarounds”.

Plan

For each bug, once the bug is “Active” or “Approved”, it is good practice for team members to create tasks in ADO to best handle all the required actions. The tasks must be linked to the bug filling the “Estimate” field according to the information provided in the estimate comment, e.g.:

Development
Test
Documentation writing
Others

If the bug was identified without a test case, a new test case at the appropriate level (unit test, component test, or product test) should be created. If the test case already exists but some test steps are missing, the test case should be updated.

A test case affected by a bug must be set to “Failed”, regardless of the bug severity. If required by the project, notes can be added to the test report, and/or the test case can be split into smaller test cases.

Fix

For ”High” and ”Critical” bugs, corrective action should be identified to avoid future regression: improvements in development, improvements in technical documentation, and new tests (automatic functional tests, unit tests, and/or test cases to be added to the test plan).

A good practice is to frequently add comments to the bug with the work-in-progress details. Once a bug is fixed and integrated into the new build, set the bug state to “Resolved”, add a comment in the discussion, and assign a bug to the tester for verification.

Code review is mandatory for new code and code changes (pull request). The bug work item must be linked to the code changes.

Verify

Once fixed, the bug is verified by the test engineer and then assigned back to the scrum master for the last check or reactivated if the issue is not resolved. It is the product owner’s responsibility to identify the most appropriate test environment.

Check DoD

Before closure, the scrum master or the product owner verifies that DoD is met.

Close bug

The product owner is accountable for the bug’s closure and can delegate to someone else.

Details

State and transitions

Figure 2: Bug State Diagram

State	Reason	Explanation
New (Assigned to: product owner or scrum master)	New	The bug is created, but no decision has been taken if it shall be implemented or not. It may be incomplete in this state.
	Investigation complete	Investigation is done, awaiting CCB decision for next step.
	Not fixed	The defect was not fixed when set to “Resolved” or “Closed”, and it needs to be re-evaluated.
	Test failed	Test failed after the defect was set to “Resolved” or “Closed”, and it needs to be re-evaluated.
Active (Assigned to: HW/SW engineer or technical writer)	Investigate	The bug is sent for investigation.
	Approved	The bug is approved by the CCB to be corrected.
	Not fixed	The defect was not fixed when set to “Resolved”, and it needs to be corrected.
	Test failed	Test failed after the defect was set to “Resolved”, and it needs to be corrected.
	Regression	A closed bug that was once fixed and verified has re-appeared. It is preferred to create a new bug when this occurs.
	Reactivated	A deferred bug is reactivated (within the same release).
Resolved (Assigned to: scrum master, test engineer, or product owner)	Fixed	The bug has been resolved and awaiting formal closing.
	As designed	The bug is suggested to be rejected. The product works as designed.
	Cannot reproduce	The bug cannot be reproduced.
	Obsolete	The bug is no longer valid.
	Resolved in error	The bug was closed without being resolved.
	Will not fix	The bug is valid. CCB decided to accept the defect for the product as reported in the bug and not to invest resources to fix it.
Closed (Accountable: product owner)	Verified	The bug is resolved and verified, and all associated work has been completed.
	Fixed and verified	The bug is fixed and verified, and all associated work has been completed.
	As designed	This is not a bug. The product works as designed.
	Cannot reproduce	The bug cannot be reproduced.
	Copied to Backlog	A post-release bug affecting an already delivered release.
	Deferred	The bug is deferred to another product release. A new bug is created in the deferred context.
	Duplicate	The bug is a duplicate of another bug.
	Obsolete	The bug is no longer valid.

Note: Streams can use different ADO templates using other states and transitions.

References

Bug Classification How-to Handle Enhancements Regression Bugs How-to Handle Bugs in Multiple Releases How-to Handle Deferred Bugs DoD for L4 bugs Definition of Ready and Definition of Done Standard Bug Template Change Control Board

Teams

Mon, 01 Jan 0001 00:00:00 +0000

In certain situations, teams are involved in process activities. A team consists of a set of persons with assigned roles.

Agile Team

An Agile Team is responsible to define, build, test, and deploy an incremental solution in iterations. The team consists of a cross-functional group with a recommended size of 5 to 11 people. The team consists of motivated individuals with delegated authority to provide functionality with built-in quality. The functionality is regularly demonstrated to show progress with working solutions for stakeholders. Any feedback from stakeholders at demos is used to improve the solution. The team members have a shared responsibility for the deliverables they provide. There can be a rotating responsibility of the roles attached to a team – e.g. the same person works as a Software Engineer, Test Engineer, and Quality Engineer depending on what work the team needs to do. The teams regularly meet and plan together at the increment planning events. It is recommended to keep the team members co-located in the same place for efficiency.

Responsibilities

The Agile Team inherits the responsibilities of the Product Owner, Scrum Master, Hardware Engineer, Software Engineer, Test Engineer, and Quality Engineer roles.
Estimates the size and complexity of the work.
Determines the technical design in their area of concern, within the architectural guidelines.
Commits to the work it can accomplish in an iteration or Increment (PI) timebox.
Implements the functionality.
Tests the functionality.
Integrate and demonstrate the functionality.
Deploys the functionality to staging and production.
Supports and/or builds the automation necessary to build the continuous delivery pipeline.
Continuously improves their process.
Learn together.

Bug Classification

Mon, 01 Jan 0001 00:00:00 +0000

This guide describes how bugs – when they are created in Azure DevOps (ADO) – also are classified to ensure that they are handled with regards to their severity and potential impact.

Together with other bug-related guides, it provides information to help ensure correct handling of all types of bugs. It relates to PCP R&D’s overall bug management process, described in How-to Manage Bugs, as visualized below.

Severity evalutation

When testing software or hardware, managing bugs can be a daunting task. With limited resources, time pressure, or upcoming deadlines - the teams quickly need to analyze and decide the order the defects should be corrected, starting with the most important ones first.

The submitter (typically the test engineer or the L4 engineer) sets the severity of the bug based on the estimated customer impact. Discuss any changes to the severity with the submitter, and document the motivation for the change in the bug work item.

If it’s a security bug, the submitter also sets the security effect. If the security effect is set to “To be determined”, it will later be evaluated by the change control board (CCB). The cyber security engineer calculates the CVSS score as part of the severity evaluation, and the severity may have to be revised based on the score. If it isn’t a security bug, make sure the security effect is set to “No security bug”.

The product manager or product owner (e.g., in a CCB meeting) typically sets priorities based on the order of importance or urgency.

Severity definition

Severity describes the failure or vulnerability impact that a bug could cause (from the perspective of) a customer, determined by the organization responsible for the software or hardware.

Evaluate security bugs with the common vulnerability scoring system (CVSS), and use FIRST’s calculator to calculate the score. Document the CVSS score, including the complete vector, the severity value, and the severity rating (low, medium, high, or critical) in the bug. For a security bug not yet released, calculate the CVSS base score. For a security bug in a released product, also calculate the temporal CVSS score.

The CCB and the cyber security engineer decide if the severity given by the CVSS score should be used directly as the severity for the bug or if the severity should be different from the calculated CVSS score. E.g., if the criticality of a component is low, the severity may be set lower than the CVSS score indicates.

1 - Critical

The bug causes impairment of critical system functions or unrecoverable data loss, and no workaround solution exists. Typically, these are bugs that stop a single function or executable, and normal operation of the function is not possible.

For the customer, the bug could cause loss of life, loss of production, or serious security/safety violations.

A critical-security bug has a CVSS score between 9.0-10.0.

2 - High

The bug causes impairment of a system function, but a workaround exists. Typically, these bugs affect functionality, produce erroneous or unexpected results or prevent the function from completing.

For the customer, the bug could cause significant instability for a function, extra effort for the workaround, or result in a customer requirement not being met.

A high-security bug has a CVSS score between 7.0-8.9.

3 - Medium

The bug causes a minor loss in a system function. Typically, these bugs produce erroneous or unexpected results. An easy workaround allows the function to continue and does not prevent further progress in other areas.

For the customer, the bug means the product requirement is met but causes customer irritation could result in a loss of sales.

A medium-security bug has a CVSS score between 4.0-6.9.

4 - Low

The bug causes inconvenience or annoyance. Typically, these are more of a cosmetic nature, such as documentation issues, spelling errors, and changes to labels or colors.

For the customer, the bug doesn’t adversely affect the function or usability.

A low-security bug has a CVSS score between 0.1-3.9.

Security effect definition

“Security effect” in the bug tracking system is based on the Microsoft STRIDE threat model.

This model looks at threats from an attacker’s perspective and defines six threat categories. If there is more than one applicable threat category, select the most relevant one.

Security effect / Threat category	Description
Spoofing	A bug that may allow an attacker to pose as something or somebody else.
Tampering	A bug that may allow modification of data or code (at rest or in transfer)
Repudiation	A bug that may allow a user to deny having performed an action. For example, if a user performs an illegal operation that the system can’t trace.
Information Disclosure	A bug that may allow exposure of information to users who are not supposed to have access to it.
Denial of Service	A bug that may deny or degrade service to valid users. These are typically bugs that affect the availability and reliability of the system.
Elevation of Privilege	A bug that may allow a user to gain increased capability, typically an anonymous or standard user that may gain root or admin capabilities. In an ICS this could also be an operator account that suddenly gains the capability of a safety user or engineer
Attack Surface Reduction	This Security Effect is not a STRIDE threat but is used to indicate an action needed to reduce the attack surface of the system. Could be to add a closure of a TCP port not needed, or by default disabling a service only needed in special use cases.
To be Determined	The CCB evaluates the security bug later
Not a Security Bug	Indicates that the bug has no known security effect.

More information about security threats and software vulnerabilities is available in the Software Vulnerabilities and Threats guide.

Priority definition

The priority indicates the order bugs should be corrected and set by the CCB. The priority is defined relative to other reported bugs. Engineers use this field to prioritize their work.

CCB is allowed to reprioritize the bugs if it helps the teams to understand what to correct first.

1 - Immediate

Correct the bug immediately - it’s blocking the development and must be fixed.

2 - High

Fix the priority 2 (high) bugs before the priority 3 (medium) bugs.

3 - Medium

Fix the priority 3 (medium) bugs before the priority 4 (low) bugs.

4 - Low

Fix the priority 4 (low) bugs if time allows.

How-to Handle Deferred Bugs

Mon, 01 Jan 0001 00:00:00 +0000

During the development of a release, if a bug is found but the CCB decides to fix it in a later version, the bug is deferred. After the official release, it will then be a known bug in the product or system.

This guide describes how to handle deferred bugs and also includes a Q&A with questions related to deferred bugs.

Together with other bug-related guides, it provides information to help ensure the correct handling of all types of bugs. It relates to PCP R&D’s overall bug management process, described in How-to Manage Bugs, as visualized below.

Note: The concept of deferred bugs applies to official releases made available to customers and technology projects. The same workflow should be applied to post-release bugs, with the exception that the reason “Copied to Backlog” should be used to clone them and to assign them to the target release. For L4 bugs, the L4 DoD must be met before taking this action, see DoD for L4 bugs.

Intended for

Configuration managers, product owners, scrum masters, and test engineers.

Activities

Identify target releases

The version to which the bug is deferred may be known or unknown at the time of deferring:

If the target release is unknown, clone the bug and put it in the backlog.
If the target release is known, clone the bug and assign it to the identified target release(s). When a deferred bug is planned for a future release, it is considered a scope bug for that release.

Close bug as deferred

Close the bug with the reason “Deferred”. Do not change any fields used for planning, such as iteration path or area path.

Note: For post-release bugs, follow the same rule and select the reason “Copied to Backlog”.

Clone bug

Note: Steps 1-5 are automatically performed if the “Clone Bug” extension is installed, see Recommended Extensions. The extension is triggered automatically when saving a bug with the state “Closed” and the reason “Deferred” or “Copied to backlog”. You can also perform the steps manually by clicking on “Clone as duplicate”.

(Automatic) Clone the bug.
(Automatic) Add “Clone of bug ID -” to the title.
(Automatic) Set “ScopeBug=True” in the clone just created.
(Automatic) Set “Cloned=Yes” in the clone just created.
(Automatic) Add a link of type “duplicate” / “duplicate of” between the original bug and the clone.
(Manual) Set the target release, see Area and Iteration Path.
(Manual) Save the cloned bug.

If the bug affects multiple releases, repeat the steps above for each release as described in How to Manage Bugs in Multiple Releases.

Details

Check the Standard Bug Template for more information about the “ScopeBug” and “Cloned” fields.

Q&A

Can I re-open a bug that has been closed as “Deferred”?

No, planning a deferred bug, e.g., deferring it to a known version or putting it in the backlog, means planning its clone, i.e., the copied bug with “ScopeBug=True.” If the team can fix a previously deferred bug within the same release (e.g., if the release deadline is postponed), the original bug can be reactivated, and the cloned ones can be closed as obsolete.

Can I close a bug as deferred if I’m not planning to fix it in a future release? No, the reason “Deferred” should only be used for bugs that should be fixed in a future release. Use the reason “Will not Fix” if there is no intention to fix the bug. In the same way, the reason “Will not Fix” should not be used to defer a bug.

Who can defer a bug?

The development teams and product owners can propose to defer a bug by commenting on the bug’s “Discussion field”. However, only the CCB can decide to defer a bug.

Why are some bugs deferred?

There can be many motivations for deferring a bug, such as the required effort to fix or test it, the risk of delaying a release, the availability of resources, or the possible impact on the system.

How to identify known bugs that have been deferred?

After the bug has been deferred and the clone has been created and linked as described above, the original bug can be found by:

State = Closed.
Reason = Deferred.

After deferring, cloned bugs will be in the backlog or in a future iteration, and they can be identified by:

State = Not Closed.
ScopeBug = True.
“HowFound” does not contain “Post Release”.

How to identify the scope bugs of an ongoing release?

Bugs are planned for the current release (e.g., by area/iteration).
ScopeBug = True.

How to identify introduced bugs in an ongoing release?

Bugs found in the current release (e.g., by area/iteration).
ScopeBug = False.

How to find the deferred bugs of an ongoing release (for decision-making before releasing)?

Query the bugs found in the release where:

State = Closed.
Reason = Deferred.

How to identify known open bugs in a release in production?

Query the bugs found in the release where:

State = Not Closed.
ScopeBug = True.

What to do if the deferred bug exists in multiple versions?

Clone the bug multiple times, one for each version where it is known to exist and needs to be fixed. In this way, its fix will be planned and tracked separately.

Is a bug closed with the resolved reason “Will not fix” a deferred bug?

No, this is not a deferred bug. Resolved reason “Will not fix” means that the bug is acknowledged as a defect, but there is no intention to work and fix it in the future.

How can I identify bugs still affecting a released product version?

Query for closed bugs where either:

Resolved reason = Will not Fix.
Reason = Deferred.
Reason = Copied to Backlog.

References

How-to Manage Bugs How-to Handle Bugs in Multiple Releases Area and Iteration Path Recommended Extensions Standard Bug Template

How-to Handle Enhancements

Mon, 01 Jan 0001 00:00:00 +0000

A work item of type “Bug” can be used to suggest an enhancement, something that is not a real defect, but an idea for improvement. This guide describes how to handle enhancements as bugs.

There are two origins of enhancements as bugs:

When the change control board (CCB) recognizes a reported bug as an enhancement.
When it for some reason is not possible to create a new feature of a good enhancement idea.

Note: Remember that all bugs (including enhancement bugs) must be deferred or closed at the end of the project, see How-to Handle Deferred Bugs.

You find further information and a Q&A about enhancements as bugs under Details.

Intended for

Configuration managers, release owners, product owners, quality control managers, test engineers, and hardware engineers.

Activities

Create a bug of an enhancement idea

(This step is only valid for the case when it is a conscious choice to create a bug of an enhancement idea.)

When creating the bug, state clearly in the description that it is an enhancement idea and the reason to why it is not possible to create a new feature as preferred.

Recognize a bug as an enhancement

After the definition of ready (DoR) is checked, the CCB decides about the bug.

If the issue reported in the bug is recognized not as a defect, but as designed or as an improvement idea, the CCB can decide to consider the suggested enhancement to improve the product. The CCB records the discussion in the bug.

Bug to feature

The product owner closes the bug with reason “As Designed” in agreement with the CCB. This reason will make sure that the bug work item is not counted as a defect in KPIs.

Then the product owner creates a new feature and links it to the bug. The feature should contain a re-elaborated description of the enhancement idea, sufficient for a feature.

The recommended link between the original bug and the new feature is “Related”. A team can adopt a different convention if desired, but it’s best to avoid parent/child or predecessor/successor as they could impact visualization in “Boards and Delivery Plans” in Azure DevOps. The link is needed only for reference purpose, the link type is not used in KPIs.

Note: Important - work item hierarchy

Each feature must have an epic as its parent. Assign an epic as parent of the new feature if a good match exists in state “New” or create a new epic as parent.

Do not break DoR/DoD (definition of done) rules: if an epic is already “Active”, do not add more features. The reason is that if more and more features are added to an epic that is “Active”, it will be very difficult to complete the epic. When the feature is added to an epic, the estimation needs to be updated. It is not necessary to invest much time to make a first estimation of the feature, a high-level estimation is sufficient at this point and can be refined later when the DoR is checked.

For example, when a new feature is created:

If an epic already exists that is a good match and is not started yet, add the feature to the epic and update the estimation of the epic.

Otherwise, create an epic to contain the feature and possibly group features from enhancement ideas in bugs. Testing the epic in this case is less meaningful, there may not be test cases associated directly with the epic, since it may contain unrelated features, so testing is performed at feature level and the parent epic can be closed when all features are closed.

Feature to completion

After the feature has been created, it follows the lifecycle of any feature, with its decision making, planning, change management, validation, etc. For example, if someone wishes the feature to be added to an ongoing release, it has to go through the change request process, it will not be automatically added to the scope.

Details

About enhancement as bugs

Enhancements as bugs are precious, as they are a way to understand the expectations of users and to capture ideas to improve our products. They can relate to existing or new functionality, and a bug work item created post release can be an enhancement too.

However, such enhancement ideas need to be evaluated and planned and they can have an impact on for example existing functionalities, release schedules, resource allocations, quality, like any other changes.

Enhancements as bugs should not be used as a way to bypass change requests, CCB decisions, requirements processes or to manipulate bug KPIs. If these processes were bypassed, there would be a high risk of feature creep, resulting in delay and poor quality to try to do too much in an uncontrolled way.

For this reason, if an enhancement idea coming from a bug is thought valuable by the product owner and the CCB, it is managed as a new feature. The following flow chart illustrates the origin and outcome of an enhancement as bug, and the table below gives examples of what is considered enhancements and not.

Enhancement	NOT an Enhancement
Suggestion to improve the user interface.	User interface does not work as designed.
New functionality or robustness improvement related to an existing functionality.	Defect with low severity.
Cosmetic improvement.	Change request for an ongoing release.
The bug creator thought it was a real defect, either found internally or created as a L4 bug, then it was recognized as an enhancement.	Real defect, hidden as enhancement bug to influence KPIs.
The bug creator had an enhancement idea and wanted to capture it and submit it.	Defect that the CCB has decided to defer or not to fix at all.

Q&A

Question	Answer
What is the severity of an enhancement as a bug?	The perceived severity when opening the bug does not matter. An enhancement as a bug is as designed, it is not a defect.
What if a bug that is possibly an enhancement is very small and a feature seems too big to manage it?	When the CCB evaluates the bug work item, the CCB can decide to accept it as a defect, most likely a bug with low severity, and to process it with other bugs. In that case it contributes to bug KPIs and it is not considered an enhancement. This choice may be controversial, and the CCB should consider the size, effort, impact and risk with respect to the planned scope and commitments.
Does the severity of enhancements as bugs affect KPIs?	Bugs closed “As Designed” do not contribute to defect KPIs.
How to propose an enhancement as a bug as a change request for an ongoing release?	Follow the steps under Activities, then open a change request for the new feature to be added to the scope.
What if the enhancement as a bug is a very big functionality or requires major changes?	If the idea is very valuable and a feature is too small, the new requirement may be managed as a new epic instead and follow the epic processes.
Do we need to reach out to the CCB / product owner before creating the bug?	Yes, it is recommended and in that case the product owner can define a feature directly instead of a bug.
Who raises an enhancement as a bug?	Any team member who is directly or not directly connected to the product and wants to contribute is welcome to propose ideas. Typical roles: software engineer, hardware engineer, test engineer.
Can an enhancement as bug be deferred?	The bug must be closed before the end of the ongoing release. If it is recognized as an enhancement, it is closed with reason “As Designed”. The linked feature is prioritized and planned like other Features, so it may or may not be included in the same release as decided by the CCB. If the bug is accepted as a real defect and not an enhancement, it must either be fixed or deferred or rejected before the end of the ongoing release.
What is a negative consequence of creating more enhancements as bugs instead of features?	It may take more time to analyze bugs and fix them, because of the “noise” created by enhancements as bugs. Instead, features can be processed directly as new ideas and will not steal time from bug analysis and bug fixing.

References

How-to Manage Bugs How-to Handle Deferred Bugs

How-to Handle Bugs in Multiple Releases

Mon, 01 Jan 0001 00:00:00 +0000

A bug can exist in multiple releases, and such bugs can be challenging to track and fix. This guide describes how to manage them.

Note: This guide focuses on bugs existing in multiple releases of the same product, it does not cover common components reused in multiple products or systems.

Intended for

Product owners and configuration managers.

Activities

Discover if a bug exists in multiple releases

It may be tricky to discover if a bug exists in multiple releases. When a bug is reported, it is a good practice to try to find out whether this bug existed in other releases.

Sometimes it is easier to find out, sometimes it may be more time-consuming and it can be considered as too much effort.

When fixing the bug, the developer may notice that the code where the code fix is necessary exists in other versions, so the bug may exist in other versions too.

When working on a maintenance release, it may be discovered that the bug exists in newer releases.

Clone bug to affected releases

For each release/version/track (that is still in an active state according to the product’s lifecycle policy) in which the bug is known to exist, clone the bug as described in the procedure below. If the bug exists in a large number of releases, the change control board (CCB) decides where it makes sense to clone it and writes this information in the bug discussion.

Note: Steps 1-5 are automatically performed if the “Clone Bug” extension is installed, see Recommended Extensions. The extension is triggered automatically when saving a bug with the state “Closed” and reason “Deferred”. You can also perform the steps manually by clicking on “Clone as duplicate”.

(Automatic) Clone the bug.
(Automatic) Add “Clone of bug ID -” to the title.
(Automatic) Set “ScopeBug” = “true” in the clone just created.
(Automatic) Set “Cloned” = “true” in the clone just created.
(Automatic) Add a link of type “duplicate”/“duplicate of” between the original bug and the clone.
(Manual) Set the target release, see Area and Iteration Path.
(Manual) Check that the “How found” field is properly filled in (“Post release” for backporting and “Forward Port” for forwardporting).
(Manual) Save the cloned bug.

Cloning the bug in this way follows the same strategy as bug deferring. This method allows to associate bugs that are copies of each other and belong to different releases.

Track decisions, planning, fixes and validation for each release

From now on, follow the normal bug management process, see How-to Manage Bugs:

The CCB can decide to fix the bug, ensuring it will be planned, fixed, and validated (including fulfillment of DoR and DoD).
The CCB can decide to acknowledge the bug but not to fix it, i.e. set the reason to “Will not fix” (see How-to Handle Deferred Bugs).

Transfer the bug fix across different releases

When possible, merging the bug fix to the branch of the target release can be an efficient way to transfer the bug fix. However, this may require additional effort, for example, if the code on the target branch is significantly different and several complex conflicts occur. The fix and the impact on different branches can be different, so also tests to validate the bug fix can be different.

Find all the releases where the bug is known and where it is fixed

Make a tree query based on the duplicate/duplicate of link type (instead of parent/child) to show all the known instances of a bug in a tree query.

For each known instance of the bug, the state and other information can be visualized in the query, showing where it is fixed, where it is planned, and where it will not be fixed.

Details

About bugs in multiple releases

A bug can exist in multiple releases for different reasons, for example:

A bug was deferred for some releases before being fixed, see How-to Handle Deferred Bugs.
A bug was found after the release.
A bug was found during internal tests before release, but the code containing the problem existed in past releases too.
A bug that did not appear before can be discovered due to a change in the code or an environment change.

The “bug in multiple releases” concept applies to releases that have been officially released to customers and internal releases, still under development.

About back- and forwardporting

Depending on where the bug is first discovered, the process of fixing the bug can be referred to as:

Backporting: fixing the bug in an older version.
Forwardporting: fixing the bug in a newer version.

Backporting does not apply to hardware.

Forwardporting is highly recommended, otherwise, a bug fixed in a previous version may re-appear in a newer version and result in a regression bug, see Regression Bugs.

When planning to port a bug already fixed in a release to a different release, the effort of all the necessary activities needs to be taken into consideration, for example, fixing code, testing, and updating documentation. Even in the case where the fix is a simple merge with very few conflicts and the test itself is quick, preparing the environment and the preconditions for testing can take a significant time.

References

How-to Manage Bugs How-to Handle Deferred Bugs Regression Bugs Area and Iteration Path Recommended Extensions

Tools

Wed, 11 Feb 2026 00:00:00 +0000

User-facing updates for the Tools section. Newest entries come first.

Ver: Tools 1.0.1 Rel: 2026-02-12

Summary

Improved link and image reliability in the To Review References content.

Fixed

Repaired broken relative links to Guides content in DevOps and document template pages.
Corrected image references to match actual file names in template and tool pages.
Fixed an incorrect absolute link for the Process Teams reference.

Ver: 1.0.0 Rel: 2026-02-11

Summary

First release.

Regression Bugs

Mon, 01 Jan 0001 00:00:00 +0000

A regression bug is a bug that causes a completed feature that worked correctly to stop working after updates (e.g., system upgrade, system patching, or bug fixes). This definition applies both before and after releasing the feature to customers.

Note: A change in a feature behavior or the removal of one feature through a requirement or a business input is not a regression bug. It is a normal development activity.

This guide describes the relevance and policies of regression bugs. Together with other bug-related guides, it provides information to help ensure correct handling of all types of bugs. It relates to PCP R&D’s overall bug management process, described in How-to Manage Bugs, as visualized below.

Why regression bugs?

Some reasons to identify and manage regression bugs are:

From a customer point of view, they could damage the perceived quality of our products, because something that was working before is broken.
From an R&D point of view:
- Understanding their root cause can lead to improvements and prevent more bugs (e.g. more effective impact analysis, code review, or regression tests).
- Regression bugs can be prioritized in a release before they impact customers.

What to do with regression bugs?

Once a regression bug has been identified:

If the release is still in progress, it must be fixed in the same release (unless the CCB approves an exception).
If the regression bug is open on a release already delivered, it must be properly planned and prioritized in the product backlog by the product owner.

Relevant fields

Regression: “False” by default, “True” if the bug is a regression bug.

This field can be set:

When the bug is created, for example, if the bug was found during a regression test.
Later when someone realizes that it is a regression bug.

Query example

Pull Request Reference

Mon, 01 Jan 0001 00:00:00 +0000

What is a pull request?

A Pull Request (PR) is a way to get your changes integrated into protected branches, making sure the changes fulfill a defined set of policies or quality gates.

Where should a pull request be used?

A pull request is used from a feature branch to a protected branch, typically to the development/integration or master/main branch. Direct commits are possible only on feature branches.

If someone attempts to commit code changes on a protected branch, git reminds the user that it’s not possible and that a pull request must be used instead.

Mandatory policies

Require a minimum number of reviewers to approve, typically 1 or 2 Code Guards
A person cannot approve his/her own code changes
A description of the content to integrate is provided by the person who creates the pull request
All comments must be resolved
Changes must be linked to a work item
Build validation

Optional policies

Tool integration, e.g. SonarQube pull request decoration
Other tools for static or dynamic code analysis could be integrated.

Customizing pull requests

A pull request template can be used to define a standard pull request description and checklist format. Azure DevOps PR template documentation

Who can approve a pull request?

The people who can approve a pull request are sometimes called Code Guards or Committers.

Pull Requests to dev/integration (or master if following a GitHub flow) should be approved by someone in the development team, but an engineer cannot approve his/her own pull request.

In some cases, anyone can contribute to a repository, but only a few selected people have the authority to approve/reject those contributions.
In some cases, any team member can approve/reject a code change, and the pull request becomes a way to ensure that the code is reviewed by at least one person other than the author before it is accepted.

It is possible to automatically add reviewers to pull requests that change files in specific directories and files or to all pull requests in a repo: https://docs.microsoft.com/en-us/azure/devops/repos/git/branch-policies?view=azure-devops&tabs=browser#automatically-include-code-reviewers

Pull Requests to Master (in the recommended Gitflow branch model) shall be approved by someone in the CM group or the Product Owner.

How to review the changes?

See the Code Review guideline.

Organization

Tue, 16 Jul 2024 00:00:00 +0000

Additional Information

Mon, 01 Jan 0001 00:00:00 +0000

Ref #	Document Kind, Title	Document No.
1.	Process, Cyber Security Management System	MP 025
2.	Process, Active Product Management (APM)	MP 001

Requirements

Mon, 01 Jan 0001 00:00:00 +0000

The requirements process describes how the market requirements are received from PM and transformed into epics, features, and stories.

The functional analysis (not the solution/design) is also part of the requirement process and how the functionality from the stakeholder perspective is captured in the user stories. Please note; that a stakeholder for a user story can be an external customer, another agile team, or anyone else requesting the functionality.

Process Overview

Principles

Analyze product and technology requirements from PM and define epics (functional and non-functional).
Analyze architecture needs and define product epics (enablers).
Break down epics into features and stories.
It is highly recommended that the size of epics, features, and stories fit within releases, increments, and sprints.
Ensure the content of epics, features, and stories is clear and precise, including description, acceptance criteria, estimates, paths, links, and security information.
Visualize dependencies and ensure consistency and traceability of epics, features, and stories.

Implemented epics/features/stories are not maintained, i.e., new epics/features/stories are defined if changes are needed

Activities

Artifacts

Artifact

Description

RACI

Receiver

Tailoring

Marketing Requirements Specification (MRS)

Needs from different stakeholders are defined as product requirements. Owned by PM

R	Product Manager
A	Product Manager
C	Cyber Security Engineer, Product Owner, Test Lead
I	Architect, Division Cyber Security Officer, Safety Engineer

Product Owner

The actual format can be decided by each agile team. The important aspect is to document the market requirements.

Technical Requirements Specification (TRS)

The Technical Requirements Specification are based on an MRS from PM. They can be refined by R&D. Enablers added.

R	Product Owner
A	Product Owner
C	Architect, Product Manager
I	Cyber Security Engineer, Test Lead

Product Owner

The actual format can be decided by each agile team. The important aspect is to document the technical requirements.

Epic

An Epic is a container for a significant development initiative that captures the more substantial investments within an agile team.

R	Product Owner
A	Product Owner
C	Architect, Cyber Security Engineer, Agile Team, Test Lead, Product Manager
I	-

Agile Team

Feature

Features are services that fulfill stakeholder needs. Each includes a name, benefits hypothesis, and acceptance criteria. They should have a size to fit within a PI.

R	Agile Team
A	Product Owner
C	Architect, Cyber Security Engineer, Safety Engineer
I	Test Lead, Product Manager

Agile Team

User Story

Functional description, shown on team boards.

R	Development Team
A	Product Owner
C	Development Team
I	-

Agile Team

Cyber Security, Safety roles should be considered when applicable.

References

Agile Requirement Structure Component Capabilities Guideline How to: work with Epics and Features Product Capabilities Guideline Requirement Review Guideline

Architect

Mon, 01 Jan 0001 00:00:00 +0000

The architect has an overall responsibility to define and describe the architecture and drive the major technical decisions.

Description

This typically includes identifying and documenting the architecturally significant aspects of the product, including requirements, design, implementation, and deployment “views” of the product.

They participate in the definition of higher-level functional and non-functional requirements, validate technology assumptions, and analyze alternative technical solutions and trade-offs. The architect is also responsible for providing the rationale for the decisions, balancing the concerns of the various stakeholders (customers, product management, suppliers, manufacturing, etc.), evaluating alternative solutions, reducing technical risks, and ensuring that decisions are effectively communicated and validated, and adhered to.

The architects support the product development by providing, communicating, and evolving larger technological and architectural views of the product. This includes decomposition into components and defines the interfaces between components and external APIs.

The architecture should also support the agile-lean mindset to increase the platform functionality in iterations and increments just in time when needed. In a situation with many teams, the architecture decomposition must also enable different teams to work efficiently and visualize the technical dependencies.

Responsibilities

Work with customers, stakeholders, and suppliers to gather knowledge about the high-level product intent and documentation requirements.
Participate in the planning, definition, and high-level design of the product and explore different design alternatives.
Establish critical non-functional requirements and participate in the definition of functional requirements together with product management and product owners.
Document and maintain architecture. Define components and their internal and external interfaces (APIs).
Plan and develop the architectural runway, i.e., identify enablers (infrastructure or architecture activities) in support of upcoming business features/capabilities.
Work with product owners to determine capacity allocation for enablement work.
Work with team members to analyze, split, prioritize, and realize the implementation of enablers in the architecture runway.
Communicate architectural aspects in the increment planning events, participate in pre-planning, demos, and inspect-and-adapt meetings (retrospectives).
Provide information to integration and test teams about the product to facilitate test development.
Supervise and foster “built-in quality” in the teams.
Analyze and coordinate life cycle aspects of 3rd party software updates (e.g., operating systems).
Has responsibility for the final check of hardware regarding the choice of components to minimize the risk to get in, for example, obsolete components, non-RoHS components, and components without a second source.

Architecture

Mon, 01 Jan 0001 00:00:00 +0000

Process Overview

Principles

Establish and maintain the product architecture based on product epics and user stories.
Define the static and dynamic architecture with components, interfaces, and interactions.
Using modular design to ensure loosely coupled components with independent lifecycles, separation of concerns, and future-proof extensibility.
Evaluate aspects of architectural and design alternatives and propose implementations.
Establish architectural roadmap and communicate technical decisions from Innovation & Product Platform to Solution Agile Units.
Include security aspects in the architecture, including the security context, threat modeling, criticality analysis, and attack surface analysis.
Continuously verify and align the architecture with the design proposed by Agile teams.
Support the Agile teams in the breakdown of architectural requirements in backlogs.
Monitor lifecycle aspects of 3rd party components and decide on upgrades, updates, and patches.

Activities

Artifacts

Artifact

Description

RACI

Receiver

Tailoring

Product Architecture

An architecture description of a product with different related components.

R	Architect
A	Product Owner
C	Cyber Security Engineer, Agile Team
I	Test Lead, Safety Engineer, Product Manager

Agile Team

Product Architecture Roadmap

The high-level plan for product architecture.

R	Architect
A	Product Owner
C	Agile Team
I	Product Manager, Agile Team

Agile Team

Optional

Product Capability

Description of what the product “can do” after implementation of epic(s)

R	Product Owner
A	Product Owner
C	Architect, Agile Team, Test Lead, Safety Engineer
I	Cyber Security Engineer, Product Manager

Agile Team

Threat Model

A model to identify potential threats, document vulnerabilities, and suggest mitigations.

R	Architect
A	Product Owner
C	Cyber Security Engineer, Agile Team, Test Lead
I	Division Cyber Security Officer, Cyber Security Specialist, Manager, Product Manager

Agile Team

Attack Surface Analysis

The set of entry points that hackers can potentially use to attack the product.

R	Architect
A	Product Owner
C	Cyber Security Engineer, Agile Team, Test Lead
I	Division Cyber Security Officer, Cyber Security Specialist, Product Manager

Agile Team

Security Context

The security expected to be provided by the environment for a product or component.

R	Architect
A	Product Owner
C	Cyber Security Engineer, Product Manager
I	Agile Team

Agile Team

Cyber Security, Safety roles should be considered when applicable.

References

Architecture Document Structure (Refer Modelling Structures) Architecture Review Checklist Architecture Review Guideline How to: Perform Threat Modeling How-to: Refine architecture Product Capabilities Guideline Product Capability Template

3rd Party Software Owner

Mon, 01 Jan 0001 00:00:00 +0000

The 3rd Party Software Owner is responsible for monitoring and maintaining 3rd-party software and open-source used in the development of ELSP products.

Description

ABB ELSP uses 3rd-party software, tools, and open-source components in the development of new products. The software needs to be monitored and maintained for updates, security, export control, and other lifecycle issues.

The 3rd Party Software Owner monitors the status of software from suppliers. It includes software integrated into ABB ELSP products and the tools used in product development. He/she also evaluates risks with Open-Source licenses and makes sure no legal aspects prevent a release.

The 3rd party software is registered in DFN, where lifecycle aspects, costs, and other issues are tracked. For Open Source, the source code is scanned by Black Duck provided by the OCC team.

The 3rd-Party Software Owners need to collaborate with other agile teams to make sure actions are planned in increments and iterations to address any issues.

There must be one or more 3rd Party Software Owners in an agile team. The role can be shared with other roles (e.g., the Product Owner is also responsible for 3rd-party software, and the Product Owner initiates OSS scans and reviews the result)

Responsibilities

Drive investigations of new 3rd party software needs.
Monitor 3rd party software lifecycle and security vulnerabilities, and security updates, and initiate new versions and updates.
Maintain 3rd party software and suppliers database in DFN (agreements, licenses, etc.).
Identify and mitigate risks for Open Source licenses, operations, and cyber security.
Ensure the 3rd party processes are followed by the agile team.
Participate in the continuous improvement of 3rd party processes, practices, and tools.
Give support to the organization about 3rd-party.
Ensure ECCN numbers are received from the 3rd-party software vendor and updated in DFN.

Software Development

Mon, 01 Jan 0001 00:00:00 +0000

Software development supports the incremental development of product features. Included are design, implementation, unit tests, component tests, and bug fixing. SW development can result in deliverables, e.g., firmware, applications, and tools. For embedded systems, the software or firmware is dependent on the hardware, and the software and hardware processes need to be tightly integrated.

Process Overview

Principles

Design and document the solution parallel with the code. Use design patterns for classes and methods.
Commit code frequently, preferably daily, to ensure quality and development speed.
Protect the code base with automated unit tests, component tests, static code analysis, and code reviews applied before acceptance.
Ensure consistency and traceability from requirements and architecture to design code and test. Continuously refactor and refine the design, code, and tests to reduce technical debt.
Provide input to end-user documentation.

Activities

Artifacts

Artifact

Description

RACI

Receiver

Tailoring

Component Capability

Describes what the component is capable to do. Lives with the component lifecycle.

R	Agile Team
A	Product Owner
C	Architect, Agile Team, Safety Engineer
I	Cyber Security Engineer

Agile Team

Detailed Design

Details the high-level design and describes the component structure with modules and classes as well as internal/external interfaces.

R	Agile Team
A	Product Owner
C	Architect, Development Team, Safety Engineer
I	Cyber Security Engineer

Agile Team

Format can be decided per Agile team.

Code

High-quality code

R	Agile Team
A	Agile Team
C	-
I	-

Agile Team

Unit test

Unit test that ensures the quality of the units/code.

R	Agile Team
A	Agile Team
C	-
I	-

Agile Team

Unit test result

Result from automated unit tests managed in tools.

R	Agile Team
A	Product Owner
C	-
I	-

Agile Team

Component test

Component test that ensures the quality of the component.

R	Agile Team
A	Agile Team
C	Cyber Security Engineer
I	Product Owner

Agile Team

Component test result

Result from automated component tests managed in tools.

R	Agile Team
A	Product Owner
C	-
I	-

Agile Team

User Documentation

Drafts of user documentation describing the functionality from a user perspective.

R	Agile Team
A	Product Manager
C	-
I	-

Product Manager, Test Team, User

Cyber Security, Safety roles should be considered when applicable.

References

ADO standard work item template change management process Code Review Guideline Component Capabilities Guideline Component Capability Template Component Test Overview Cyber Security in User Documentation How-to Manage Bugs Describe the Usage of SCA Tool Template Performance Testing Pull Request Reference Recommended Component Test Frameworks Recommended Unit Test Frameworks Secure Coding Guideline Secure Coding Guideline, .NET Secure Coding Guideline, C Secure Coding Guideline, ReactJS Software Artifact Model Static Code Analysis Test Techniques Unit Test Overview Unit Test Writing Guideline

Chapter Lead

Mon, 01 Jan 0001 00:00:00 +0000

The Chapter Lead acts as a line manager and is responsible for a set of employees.

Description

He/she is actively involved with the teams, and provides support, encouragement, and delivers positive and constructive feedback daily. The Chapter Lead can influence team member satisfaction and engagement. As a result, he/she has an indirect impact on organizational productivity and even customer satisfaction.

The Chapter lead develops the talent of his organization by identifying, developing, and promoting professionals in the teams.

He/she is also responsible for proper competencies available in his/her Agile Unit, and to take action to close competency gaps.

Responsibilities

Recruiting and hiring talent to fill team positions.
Providing training and support to new hires.
Cross-training employees to ensure job rotation and minimize assignment coverage gaps.
Providing coaching and performance feedback to all team members.
Communicating and ensuring understanding of functional or departmental goals.
Monitoring individual and team metrics and performance versus targets.
Identifying the need for corrective actions.
Ensuring quality standards for all processes.
Evaluating overall team and individual performance and delivering performance reviews.
Engaging and coordinating with other line managers across the organization.
Providing reports on productivity and other performance indicators to management.
Identify competency gaps and ensure employees have the necessary training to perform their job.
Ensure competency transfer when the employees leave or transfer to new assignments.

Test

Mon, 01 Jan 0001 00:00:00 +0000

The products are tested to provide stakeholders with information about the quality of potential deliverables or releases.

Testing on software levels (unit and component tests) is described in the respective processes software process, and hardware process.

Security testing is a part of testing at all levels. For more information about Security testing, see 3BSE070423 Security Testing Guideline.

Process Overview

Principles

Each Agile team / release shall establish a test strategy that details the test activities based on specific needs.
Strive for automated tests, when possible, to reduce manual and repetitive work.
Continuously integrate and test to find bugs early and fail fast.
Product tests shall ensure the epic’s acceptance criteria are fulfilled.
Test performance and scalability and identify potential vulnerabilities.
Summarize the final performed tests and conclusions in a test report.

Activities

Artifacts

Artifact

Description

RACI

Receiver

Tailoring

Product test strategy

Test strategy for a product release (including the needs for test environments and test applications).

R	Test Lead
A	Agile Team Owner / PO
C	Architect, Cyber Security Engineer, Agile Team, Product Owner, Quality Control Manager, Agile team
I	3rd party SW engineer, Product Manager

Agile Team

The format can be decided per agile team.

Product test case

Test cases executed in the Product Test Environment.

R	Agile team
A	Test Lead
C	Cyber Security Engineer, Agile team
I	Agile Team, Product Owner

Agile Team

Product test result

The outcome of executed test cases is documented in the test tool. Only the final test result is reviewed and approved.

R	Agile team
A	Product Owner
C	Test Lead
I	Cyber Security Engineer, Quality Control Manager

Agile Team

Product test report

A report summarizing qualitatively and quantitatively the outcome of the tests.

R	Test Lead
A	Product Owner
C	Agile team
I	Cyber Security Engineer, Agile Team, Quality Control Manager, Product Manager

Product Owner

Product test environment

Description of the product test environment.

R	Agile team
A	Test Lead
C	Architect, Product Owner
I	Cyber Security Engineer, Product Manager

Agile Team

The test environment can be included in the test strategy for smaller configurations.

Product test applications

Product test applications needed to execute tests.

R	Agile Team
A	Test Lead
C	Product Owner
I	Chapter Leader

Agile Team

The test applications are part of the test environment and are managed as code.

Cyber Security, Safety roles should be considered when applicable.

References

3BSE070423 Security Testing Guideline

How to: Create a test plan in ADO Product Test Test Overview Test Phase Checklist

Cyber Security Engineer

Mon, 01 Jan 0001 00:00:00 +0000

The Cyber Security Engineer is knowledgeable in product-related security issues and assists other roles in writing cyber security requirements, assisting with secure design, secure coding practices, security testing of software for products, and assisting the product maintenance, e.g., with vulnerability handling.

Description

The main work of a Cyber Security Engineer is to assist the agile team and software, hardware, and test engineers with product-related security issues and solutions.

Collaboration is an integral part of the job, as the Cyber Security Engineer may be consulted by managers, customers, and developers to solve technical challenges and determine the requirements of the product.

Products and components must be compliant with ABB’s Minimum Cyber Security Requirements for Products (9ADB005793). Apply, when applicable, Cyber Security Requirements for Project Deployment (9ADB006087) and Minimum Cyber Security Requirements for Service (9ADB007833).

Responsibilities

Regularly inform and train employees in Cyber Security.
Assist product management in capturing customer-driven product requirements on Cyber Security.
Ensure that cyber security practices are followed (e.g., security assessment, threat modeling, static code analysis, product validation, DSAC testing, reviews, etc.).
Defining and documenting the security architecture of the product.
Ensure 3rd party Software (e.g., open-source) are validated for Cyber Security - this includes monitoring and managing security updates of the 3rd party Software.
Ensure that used tools (e.g., Static Code Analysis) are configured and updated according to recommended security guidelines.
Ensure test products are installed with appropriate security settings and security updates.
Ensure compatibility between the products and 3rd party security products is validated (e.g., antivirus SW or application white-listing SW).
Provide input about security recommendations to user documentation.
Ensure Cyber Security deviations and issues are resolved, and when necessary, escalate issues to the Cyber Security Manager.
Ensure discovered vulnerabilities are managed according to the vulnerability handling process, including support for publishing the related field communication.

Release

Mon, 01 Jan 0001 00:00:00 +0000

The Release process deploys new functionality into production (continuously or on demand). It ensures all deliverables are ready to release.

Process Overview

Principles

Establish release scope and associated products to be released.
Determine the delivery media type for the release.
Define and produce the product release documentation (3rd party, Security, Export control, standards, certificates, …)
Ensure product release approval before delivery.
Provide a release note detailing key characteristics of the release.

Activities

Artifacts

Artifact

Description

RACI

Receiver

Tailoring

Release Roadmap

Shows the overall releases by an agile team, 3-4 increments ahead

R	Agile Team
A	Product Owner
C	Agile Unit Lead, Agile Portfolio Manager
I	Chapter Lead

Agile Team

OSS Scan & Clearance Report

OSS Clearance report from Black Duck.

R	Agile Team
A	Product Owner
C	Chapter Lead
I	-

Agile Team

Release Media

Files needed for manufacturing/Distribution to customers

R	Agile Team
A	Product Owner
C	-
I	-

Operations

Security Assessment Report

Final security assessment report for the release.

R	Cyber Security Engineer
A	Division Cyber Security Officer
C	Head of Cyber Security
I	3rd party SW engineer, Architect, Agile Team, Product Owner

Certificates

Certificates for the releases(ATEX, Safety, UL, CSA, GM, CE, etc.).

R	Agile Team
A	Product Owner
C	Chapter Leads
I	CoE Leader for Certification and Standardization

Release Notes

Summary of the release contents, major issues and work-around

R	Agile Team
A	Product Owner
C	Chapter Lead, Technical Coordinator, Test Lead, Safety Engineer, CoE Certification and Standardization
I	-

Operations

Export Control

Provides information for ECCN classification for software and hardware.

R	Agile Team
A	Product Owner
C	Chapter Lead, Product Manager
I	-

Agile Team

User Documentation

End-user documentation about product, or application.

R	Agile Team
A	Product Owner
C	Sales Team, Test Lead, Safety Engineer
I	Sales Team

Cyber Security, Safety roles should be considered when applicable.

References

Cyber Security In User Documentation Release Stages

Active product management

Mon, 01 Jan 0001 00:00:00 +0000

MP 001 Active Product Management is the main process to manage engineering changes to products released to customers. Engineering change can be triggered by quality issue in field, quality issue identified during internal testing or in production, or by internal employees that see potential for improvement (e.g. optimization, cost reduction, materials obsolescence etc.).

DevOps Specialist

Mon, 01 Jan 0001 00:00:00 +0000

Development, Quality Assurance, and Operations are key elements in DevOps. This concept includes the entire agile and lean culture, and at ELSP Agile Unit, we want to fully embrace this working paradigm.

Description

The DevOps team will support a firm handshake between development and R&D operations that emphasizes a shift in mindset, better collaboration, and tighter integration. It unites agile, continuous delivery, automation, and much more to help agile teams to be more efficient, innovate faster, and deliver higher value to businesses and customers.

Full-fledged DevOps will not be applicable to all the Development Agile Units. In some of them (e.g., Engineering, Operations, and Controller & I/O), a reduced set of practices are implemented.

Responsibilities

Define, support to initiate and coach/train DevOps Implementation for ELSP Agile Unit.
Advice about processes and tools and technical support to make DevOps successfully implemented by Agile teams.
Consultant in the implementation of a highly automated CI/CD pipeline in order to deploy new software quickly and implement different kinds of product design.
Responsible for advice about the proper tools and processes that can automate any manual tasks.
Identify DevOps improvement potentials across ELSP Agile Unit and drive its implementation.
Share improvements and successes within the R&D community.
Ensuring that the different teams work together on common objectives towards quality and velocity of software delivery.
The DevOps team is the coach for the DevOps initiatives implementation.
Advice about development KPIs and support its implementation and tracking.

Functional Safety Management (FSM) Manager

Mon, 01 Jan 0001 00:00:00 +0000

The Functional Safety Management (FSM) Manager is responsible for ensuring that the R&D organization adheres to the applicable functional safety standards, such as the IEC 61508 or IEC 61511, for safety-related development and maintenance.

The role is mandatory for any safety-related development or maintenance project.

Description

The FSM Manager is responsible for ensuring that normative requirements of the safety life-cycle phases are fulfilled for the safety-related products and projects. He/she does so by monitoring and controlling that processes and development work follow the standards and that functional safety is achieved and demonstrated within the R&D organization.

The FSM Manager may delegate the responsibility to other roles, such as the Safety Engineer (SE), and/or teams, such as the Safety Team (whose members consist of the SEs).

Responsibilities

Ensures adherence to the applicable functional safety standards of the safety-relevant parts of ELSP Agile Unit QMS.
Ensures correctness and completeness of all safety-related instructions and guidelines.
Approves the safety-related documentation, such as the Quality & Safety Plan & the Safety Manual, from an FSM perspective for safety-related projects.
Monitors the adherence of the safety-related projects to the safety standards and processes via the safety assurance activities e.g. via the safety assurance assessments and via dialogue with the Safety Engineers who define, coordinate, participate, and/or conduct safety-related activities both between and within safety-related development projects.
Supervises that handling of field problems with safety relevance is handled the correct way, e.g. in time, the right action(s), etc.
Trains and coaches in the Functional Safety procedures and methods.
Performs internal FSM audits.

Competence

Undergone IEC 61508 Functional Safety training either in-house or externally.
At least 3 years of business experience in the area of Functional Safety is desired.
At least 3 years of business experience in the leadership position of the organization is desired.
Higher technical education, degree or diploma, in a related discipline or equivalent engineer level responsibilities status certified by an employer in a reference letter.

Process Owner

Mon, 01 Jan 0001 00:00:00 +0000

The process owner is responsible for creating, sustaining, and improving a specific process and has the authority to make the required changes to achieve the objectives of the process.

Description

The process owner is a subject matter expert (SME) of the specific process but also has a broader understanding of interactions and interfaces to other processes and organizations. The process owner should have knowledge about process development methods and tools (Six Sigma, PDCA, fishbone, etc.).

The goal for the process owner is to keep the processes as lean as possible, supporting a lean-agile approach with iterations and increments. The processes should be adaptable and possible to tailor to an agile team’s needs, where required boundaries (e.g., due to standards) are clear. Tools are utilized to support continuous development (DevOps) and automate activities where possible.

The process owner collaborates with the practitioners of the process to collect feedback and improve the process. KPIs and discipline dashboards are monitored to ensure the process is efficient and meets the needs. The process owner collaborates closely with OpEx and the R&D Quality Manager to resolve issues and other organizations with process interfaces.

For large initiatives (e.g., introducing new tools), the process owner can act as a project manager and lead a team for the changes. The process owner can request resources in the R&D organization to support implementing changes.

Responsibilities

Ensuring the purpose and objectives of the process are clear.
Explain, support, and train practitioners in the process.
Determine and implement KPIs and discipline dashboards, evaluate the result, and take corrective actions to ensure processes are efficient and followed.
Ensuring the process fits the needs of many agile teams, and it is possible to tailor it to specific agile team or agile unit needs.
Ensuring efficient integration with other processes and collaborating with other process owners to optimize across processes.
Reviewing contents, at least every 3 years, approving, and communicating process changes and changes in tools.
Manage process change requests to closure.
Escalate process issues and interruptions to the R&D Quality Manager and OpEx when necessary.
Work closely with teams to pilot, introduce changes, communicate, and support the practitioners of the process.
Participate in audits when requested (e.g., ISO, Security, Safety, and customer audits).

Product Owner

Mon, 01 Jan 0001 00:00:00 +0000

The product owner (PO) is responsible for defining and prioritizing epics, features, and stories in the agile team’s backlogs to implement business-specific solutions.

Description

He/she shall assess the new development’s impact on the overall system.

He/she also synchronizes priorities from different stakeholders to streamline the execution while maintaining the conceptual and technical integrity of features or components the team is responsible for. The product owner also has a significant role in ensuring quality and is empowered to accept or reject deliverables.

The role has significant relationships and responsibilities outside the local team, e.g., participation in product management activities and ABR/QBR planning. Ideally, the product owner is collocated with the agile team, where they typically share management, incentives, and culture.

Responsibilities

Coordinate with product management to define product-level epics and features, clarify/detail those when needed.
Ensure that epics and features are defined, prioritized, and fulfilled “Definition of Ready” before entering the increment planning.
Perform requirements feasibility, and impact analysis.
Plan and carry out product discovery sessions to build a product backlog, estimate the work, and plan incremental releases.
Ensure team deliverables in increments are on time by managing risks and maximizing learning while building software and hardware.
Create alignment with the team, stakeholders, and product managers, around common product feature goals, coordinating dependencies.
Participate in the definition and breakdown of market opportunities (business and technical) to features and user stories.
Accountable for ensuring quality; he/she has the authority to accept or reject deliverables from teams based on “acceptance criteria” and “definition of done”.
Participate in sprint planning meetings to break down user stories into tasks.
Ensure the team is committed to the scope and priorities before the sprint starts.
Prepare and conduct increment planning and demos.
Prioritize and include maintenance support cases in the backlog together with product management.
Analyze, prioritize, and manage change requests until closure.
Initiate maintenance of released products (service packs, roll-ups, temporary corrections, etc.).
Support the system test team by reviewing system test cases and acceptance criteria.
Participate in demos.
Review documentation.

Scrum Master

Mon, 01 Jan 0001 00:00:00 +0000

The Scrum Master is a servant leader and coach for an agile team. They help educate the team in Scrum, Kanban, and Lean, ensuring that the agreed Agile process is followed.

Description

They also help remove impediments and foster an environment for high-performing team dynamics, continuous flow, and relentless improvement.

He/she enables teams to self-organize, self-manage, and deliver via effective Lean-Agile practices. The Scrum Master supports and enforces the Scrum process and other rules agreed upon by the team. The Scrum Master also helps the team coordinate with other teams and communicate status to management as needed.

Responsibilities

Facilitates daily scrum meetings, sprint planning, sprint reviews, and retrospective meetings.
Facilitates the management and tracking of the sprint backlog, giving support in writing, estimating, and splitting user stories.
Facilitates cooperation with stakeholders such as customers, teams, product owners, management, etc.
Helping the team to stay focused and protecting the team against external distractions.
Ensure the team agrees on the “Definition of Done,” and that activities and deliverables fulfill the criteria.
Helping the team to reduce risks and remove impediments raised by the team.
Coaches the team to become self-organized.
Coaching the team in understanding the Scrum method (values, practices, events, etc.) until fully adopted and understood.
Helping the team to reflect on Agile and Scrum values and continuously improve their working method.
Helping the team understand the need for clear and concise user stories.
Working with other Scrum Masters to increase the effectiveness of the application of Scrum in the organization.
Helping employees and stakeholders understand and enact Scrum.
Promotes “built-in quality.”

Software Engineer

Mon, 01 Jan 0001 00:00:00 +0000

The Software Engineer creates high-quality software solutions (incl. FPGA) by analyzing requirements and designing, developing, integrating, and testing software for products.

Description

The Software Engineer implements solutions, including testing and debugging the software. Also included are maintaining and improving the software once it is in operation. For new development, different solutions should be evaluated. The best possible solution is selected depending on value, cost, or any other constraints.

Collaboration is an integral part of the job, as developers frequently consult with management, customer, and other developers to solve technical challenges and determine the requirements of the software product.

Software Engineers are problem-solvers who possess analytical skills and the ability to think outside the box and comprehend advanced and complex technical products in a customer context. The solution provided by the software engineer must be professionally developed and adhere to relevant standards, guidelines, and instructions.

Responsibilities

Understand the customer requirements and propose a possible solution (evaluate alternative solutions based on value, cost, quality, technology, etc.).
Design and implement the solution.
Ensure the quality of the solution (code reviews, static code analysis, code coverage, unit tests, etc.).
Integrate the solution into the product, and ensure it works as expected.
Improve the quality of existing software (correct defects, root cause analysis, etc.).
Increase knowledge of relevant new technologies that can be used in the future.
Work collaboratively and professionally with other colleagues in cross-functional teams to achieve goals.
Apply a sense of urgency, commitment, and focus on the right priorities in developing solutions in a timely fashion.
Provide information for manuals and review them for technical accuracy.
Ensure required policies and standards are followed (Safety, Security, Open Source, etc.).
Ensure the required guidelines and instructions are followed (configuration management guidelines, style guides, etc.)
Utilize modern software engineering tools (Azure DevOps, SonarQube, Klocwork, etc.).

Test Engineer

Mon, 01 Jan 0001 00:00:00 +0000

The Test Engineer develops tests (test cases, test methods, test applications), performs the tests, reports the test result, and verifies the symptoms of reported defects.

Description

The developer and tester roles overlap in a scrum team, and the same person may perform both roles.

Responsibilities

Develop and perform tests according to the requirements, test strategy, and test plans.
Report quality issues and verify corrections.
Communicate the test result to the PO and agile team member and other stakeholders.
Choose different test methods depending on the test object.
Cooperate with developers and product owners to define test cases and resolve issues from test execution.
Configure and set up the test environment and test lab, and develop test applications (simulations, load tests, device configuration, etc.).
Test Automation framework/code design to convert manual test cases to automatic ones.
Perform pre-DSAC test.
Focus on functional testing and exploratory testing.
Conduct end-to-end workflow testing.
Follow the DoD, like User Manuals Verification and Acceptance criteria for validating any User Story / Feature.
Provide fast feedback to developers.
Follow DevOps principles and increase the agility of deliverables without compromising on quality.

Test Lead

Mon, 01 Jan 0001 00:00:00 +0000

The Test Lead has the responsibility for planning, performing, and evaluating tests before products are released.

Description

He/she collaborates with product owners, teams, and other stakeholders to understand the requirements and how to verify them.

The Test Lead ensures (together with Test Engineers) that the requirements are testable by working with the Product Owners to define the acceptance criteria for features. The Test Lead collaborates with the Product Owner and provides the result of the tests before the feature is closed.

The overall test result is communicated to stakeholders by the Test Lead. Critical and high-level bugs are followed up to closure with the teams. The Test Lead is also responsible for creating an efficient test process and test environment. He/she promotes automated tests when it is possible from a time/cost perspective.

The Test Lead role exists in an agile team when there is a need to manage tests and coordinate test engineers from a product perspective.

Responsibilities

Release-wise test plan creation, considering all product integration test strategies at the product level.
Tracking all test artifacts and test metrics.
Highlight all issues/concerns/blockers.
Synchronize with other Test Leads and track the test progress.
Focus on stabilization at the product level and validation of all functional & non-functional requirements on the Epics level and follow DoD with acceptance criteria defined and all product-level documentation validation.
Support DevOps & OpEx for continuous feedback.
Provide demo to relevant stakeholders.

Mon, 01 Jan 0001 00:00:00 +0000

Is the code reviewed and issues fixed?
Is the static code analysis performed and issues fixed?
Is the user documentation, including release notes, updated?
Is the architecture and design documentation updated?
For security-critical components and security-relevant bugs, are the threat models, attack surface and criticality analysis, and the security assessment updated?
Are the unit, functional, and/or security tests updated and passed?
Are other similar issues identified?
Are bugs created for other affected products or product versions?

Mon, 01 Jan 0001 00:00:00 +0000

All child features are closed
All product integration tests (PIT) passed, and existing bugs have CCB decision
Product-level documentation approved
Epic demonstrated
Input to end-user documentation and release notes provided
Installation/delivery package updated

Mon, 01 Jan 0001 00:00:00 +0000

All child stories are closed
All unit and component tests passed
Component documentation approved
Demo performed (or planned)

Mon, 01 Jan 0001 00:00:00 +0000

Confirm tasks are completed.
Impact on architecture, design, and interfaces identified and updated.
Code reviewed and issues fixed.
Static Code Analysis is performed, and issues are fixed.
Unit tests passed and included in the automated test environment.
Cumulative unit and functional regression tests passed.
End-user documentation is updated.
The story fulfills the acceptance criteria.

Mon, 01 Jan 0001 00:00:00 +0000

Is sufficient information available to evaluate the bug (e.g., images, dumps, log files)?
Can the problem be reproduced?
Are severity, priority, and security effect assigned?

Mon, 01 Jan 0001 00:00:00 +0000

Understandable Title and Description
Testable acceptance criteria established
If/how to demo defined
Effort estimated
Link to System Epic
Dependencies to other Epics defined
Preliminary stream architecture
Draft features
The area and iteration path is set
Security impact considered
The epic is ranked in the backlog
Epic reviewed

Mon, 01 Jan 0001 00:00:00 +0000

Understandable Title and Description
Testable acceptance criteria established
If/how to demo defined
The feature is estimated to ensure it can be completed in an increment
Preliminary design ready
Draft user stories
Link to Epic
Dependencies on other features defined
The area and iteration path is set
Security impact considered
The feature is ranked in the backlog

Mon, 01 Jan 0001 00:00:00 +0000

The story is clarified and accepted.
Enough information is provided to be able to start task breakdown by the teams.
The story is estimated to ensure it can be completed in a sprint.
Acceptance criteria are provided and agreed upon.
The story/enabler is aligned with the architecture.

Mon, 01 Jan 0001 00:00:00 +0000

Functional: The title/description/acceptance criteria come from an approved system requirement
Enabler/Architectural: Understandable title, description and acceptance criteria
An initial breakdown into epics involving streams
The system epic backlog shall be ranked for the target release
Area path set

Agile Requirement Structure

Mon, 01 Jan 0001 00:00:00 +0000

The agile requirement structure shows the breakdown of agile requirements in Decision Focus (within Portfolio and Product Management (PPM)) and Azure DevOps (within PCP R&D). The system requirements from PPM are mirrored to system epics in Azure DevOps (ADO) for further refinement.

This guide gives an overview of the different levels of requirements and their analysis, planning and execution. It also includes a Q&A to further clarify requirements-related questions.

Intended for

Product owners.

Overview

System requirements

A system requirement describes an addition, or delta, to an existing release.
A system requirement is a market requirement based on customer needs.
A system requirement can be a requirement on a system-, product- or component level, or a non-functional requirement (NFR) such as performance, standards, or legal.
Change requests on system requirements are managed in Decision Focus.

System epics

System epics in ADO are cloned from system requirements in Decision Focus.
Additional system epics can be created by R&D (enablers, e.g., architectural, improvements, preparing test environments, and developing tests).
System epics are analyzed by R&D and broken down into epics.

Epics, features, stories

An epic is preferably solution-oriented with clear objectives.
An epic can only be assigned to one development stream (split if needed).
A feature can only be assigned to one team (split if needed).
Only prioritized epics are broken down for the next increment (not all upfront).

Agile requirement structure

The system epics are broken down into epics and assigned to system streams or development streams. The system epics are kept in a “holding area” in ADO (SPI Coordination) until they can be analyzed and broken down into epics. The product owners in the different streams collaborate to break down the system epics into epics. All epics are assigned to streams, and the streams can start working on them when capacity is available.

Analysis & planning

After the system epic is created in ADO (automatically synchronized), it needs to be initially analyzed. The system epic, which describes a customer’s need, is broken down into solution-oriented epics that can be delivered and tested by a stream. Store the analysis result in the epic or write an implementation proposal (IMP) for large and complex investigations.

Make a high-level estimate of the epics and aggregate the result into the system epic. The system epics can then be an input to the release roadmap, which shows targeted completion dates for them. Later, when the epics are broken down into features before the program increment (PI) planning, aggregate and update the estimation of epics and system epics, and refine the release roadmap with the new estimations.

The result of the ranking of system epics, and epics, can be used for capacity planning across streams.

Planning and execution

Epics are the carriers of information to the streams to initiate breakdown into features and stories. The epics are part of the stream’s release roadmap and show the high-level planning for a stream. However, the features are the “fuel” for the teams, and the features are prepared (estimated and ranked) before the PI planning. The number of features brought into the PI should be matched to the increment capacity to avoid wasting excessive time for refining and planning features.

Characteristics of Agile Requirements

Type	Description	Size	Tool
System requirement	Describes a customer need (not a solution/implementation) in Decision Focus. Can result in changes in systems, products, or components.	Must fit in a release.	Decision Focus
System epic	Basically, the same thing as an system requirement, but in ADO. R&D can create additional system epics (enablers) if needed.	A system epic spans over several SPIs but must fit into a release.	ADO
Epic	Larger solution-oriented initiative preferably contained within one stream.	Can span over several PIs but must fit in a release.	ADO
Feature	Smaller addition to a release, verified in component or product tests.	Can span over several iterations but must fit in a PI.	ADO
Story	Stories are short descriptions of a small piece of desired functionality written in the user’s language.	Must fit in one iteration.	ADO

Extending with product and component capabilities

The requirements should reflect the complete product for current and all previous releases over the product’s lifecycle. E.g., when an epic or feature is completed, the corresponding product or component capability is updated to reflect the additional change (delta). See Product Capabilities for further information.

Questions & answers

Q: What is an enabler?

To implement a business epic/feature/story, you may need to implement some basic technology or platform functionality, a.k.a. enabler. Identify such enablers when the business epic/feature/story is analyzed. R&D adds the enablers to the backlogs.

Other types of enablers, such as infrastructure, compliance, and improvements, need to be considered as well. They also require resources and should be identified and planned.

What is a system requirement?

A system requirement is a requirement captured in discussions with customers by product management. System requirements are also created for, e.g., standards, compliance, and NFRs. The system requirement should explain the functionality expected to be developed, not the solution.

Q: Why is the size of a system requirement / system epic important?

The size is important! System requirements that come from PPM are of various sizes. The epics (and features) in the streams should be of similar size (to keep a continuous flow of completed epics - it is easier to show progress and become predictable). Even if the size of system requirements may vary, try to keep a similar size of business and architectural epics in the streams. It helps the product owners break down epics into features if they are of similar size (otherwise, merge or split them).

Agree with PPM on a suitable minimum size. If the system requirements are very small, R&D should not break them down further. A small system requirement results in even smaller epics/features/stories, and the administrative costs may increase.

Q: Does PPM provide requirements for NFRs, compliance, and standards?

Yes - according to PPM, they manage these requirements as well.

Q: What does R&D verify - system requirements or system epics?

System epics exist in ADO and can be used to trace other work items in ADO.

If system requirements are verified, then R&D verifies the customer requests. If system epics are verified, both business (based on system requirements) and enablers (architecture) are tested. Also, consider how the NFRs are managed (as system requirements in DFN, system epics in ADO, or documented separately).

Q: What is verified by component, product, and system tests?

Good question - it needs to be clarified!

Either there is a clear mapping, e.g., test stories in component test, features in product test, and epics in system test. Or there is a loose mapping, where it is up to the team/stream to decide where a story/feature/epics are verified depending on characteristics, test environment, or capacity. Both alternatives are used today.

Q: Do we need to verify enablers?

Enablers are tested indirectly with the business epics/features/stories tests. Some architectural enablers that define e.g. APIs for external users in the platform, should be verified.

Q: How do we refine estimates of epics and features?

Make a quick estimate of the epics or features without breaking them down. This estimate is good enough to decide if they can be included in the increment. Then, when you break down the epic into features, estimate the features and aggregate them into a new estimate of the epic.

There’s no need to break down everything from epics to stories before M2/G2. Provide high-level estimates on all epics included in the release and break down the high-priority epics into features included in the next increment.

References

Product Capabilities

Architecture Document Structure

Mon, 01 Jan 0001 00:00:00 +0000

This document provides a guideline for structuring architecture documentation in the PAPCP R&D environment.

Other guides have described how an architecture document shall be written and reviewed, in this document, we will describe how different documents shall be organized and linked to support navigation and understandability to different categories of users.

Intended for

Architects.

Architecture organization

It is important to remember how the architecture organization works in PAPCP to understand how architecture documentation should be structured since documentation should adapt to this.

This diagram shows how architecture spans from the system architecture down to individual software module architecture and how different teams contribute to it. It becomes increasingly evident that good governance needs to be enforced to guarantee consistent documentation.

Tooling and techniques

Within PCP, it’s recommended to write design documents in Markdown and publish the .md files on wiki pages (available wiki pages for different architecture levels are listed and linked to under References). Still, the scope of such documents isn’t clear, neither the toolchain to create them.

It’s highly recommended that we follow a consistent documentation flow, which could ideally span from a high-level architecture to lower details. Such a method would nicely map to our organization, too.

To support such a documentation strategy, we sponsor the use of C4 modeling, which conceptually layers the architecture documents starting from a high-level context down to the software modules’ UML description.

C4 doesn’t describe how the architecture documents should be written; it is just a conceptual guide that gives directions and formalities for describing a software system with a progressive number of details.

The image below (from the C4 modeling website), with an analogy to Google Maps, shows how a high-level design document can be mapped to the world map, while a UML description of a code module can be mapped to pictures in Google Street View.

In the next paragraph, how this mapping would work in the PAPCP organization is explained.

C4 Modelling, although it comes with a specific formal representation of objects (the 4 Cs), doesn’t rule over any specific tool to be used to create C4 diagrams. However, several tools can be used for the creation of the diagram. Some of them are “WYSIWYG” (what you see is what you get), like VISIO (with C4 stencils add-on), PowerPoint (with C4 template), or Draw.io (with C4 extension). Others are based on scripting.

The last suggestion is PlantUML with a C4 extension; see References for more details. It isn’t a visual tool but allows you to easily create diagrams without drawing directly but just via a text-based interface. This can be convenient during reviews to annotate comments, which is harder to do on pictures. Moreover, PlantUML can be integrated into an integrated development environment (IDE) such as VSCode to simplify the editing.

Different technologies can be combined to produce C4 diagrams. For example, PlantUML might not be easy to use for very complex diagrams since there are fewer chances to influence the drawing rendering, so other tools, such as draw.io, might be more useful. The overall result by combining the drawing in a single wiki will be successful since the formal representation is the same independently of the used tool.

Besides C4

Architecture documents can be very complex and may require a different kind of diagram to represent the software behavior. It is important to understand that C4 isn’t replacing any of the best practices for documenting system interactions but is giving extra tools to describe an outside-in view of a complex system.

All the usual best practices used to describe dynamic behavior, such as sequence diagrams and static aspects, such as deployment diagrams, shall still be used in the proper C4 layers. In the code layer, for example, it is still a good practice to use UML to describe the details of the software.

Some topics, such as information modeling, may not easily map to any of the C4 layers, and in different cases, it may apply to more layers. A possible approach could be creating dedicated sections in the document describing the context, container, or component that owns those parts of the system information model.

C4 modeling and PCP architecture documentation mapping

Previous sections cover:

What does the PCP architecture organization look like (and how does it map to development streams)?
How is a logical flow of architecture documents created (and which tool should be used)?

In this section, these two things are combined to define which architects should work in which documentation area.

The following picture shows, on the left side, the different architecture teams (as described earlier) and the C4 layers.

The picture shows the following responsibilities:

System architects: Are mainly responsible for the context view. At this level, the system is described in an abstract way, including the cooperating external systems. But considering that system architects are even the “head of architecture” of a certain stream, they will have to support the definition in more detail of a certain system function they belong to. Therefore, they will also be responsible for the container view level.
Stream architects: They work most of the time at the level of container view, where they explain how a certain subsystem will work and its internal details. They are also responsible for defining the component view details of the container they have worked with.
Development teams: Are responsible for describing the details of the code modules they implement. Depending on the needs and processes behind them (e.g., UML or simply descriptive Markdown pages), the description can involve more or fewer formalities.

One crucial aspect to consider is that the wiki pages where the architecture documents will be stored will be different depending on the different layers (see links under References). Still, for the code level, the description shall stay with the repo of the code module it describes. This will help in packaging the description of the code module together with its code and version it in the same way.

C4 modeling mapped to our organization and wiki pages in ADO enables a reading flow for multiple users. We can read it from the top down (starting from the high-level context in system architecture and going down to the level of details we’re interested in) or bottom-up (starting from a code module and going up to the context where it is supposed to be used). In this way, differently skilled people can read the documents the way they prefer or need.

Certificate management is a broad topic that starts from system architecture, where we describe how certificates are issued and distributed to different system parts (e.g., Runtime, Engineering) and how their life cycle is managed. This part of the description shall be stored in the system architecture wiki with context and container diagrams. The implementation details on certificate distribution and the components involved shall be described in the stream architecture wikis (mainly Operations and Engineering). At the same time, the code module description shall be consistent with the certificate management implementation. With proper hyperlinks in the Markdown pages, navigating through different areas of the wiki pages smoothly will be possible.

The following picture sketches what’s described above in a single diagram, showing the connection across the different wiki pages, their grouping, roles, and responsibilities.

Considerations on C4, wiki and AV

The overall Automation Vision (AV) system is going to be described by the collection of all the wiki pages in the different repos at different C levels. However, the architecture documents shall be agnostic from the products that will incorporate the NextGen technology or from the different deployment options. Nevertheless, references to products and deployment are allowed for easy navigation to the proper documents, but no extensive description shall be part of the technical documents, they have to be kept intentionally abstract from the deployment and product branding.

We shall avoid mentioning System 800xA or Symphony Plus, as well as panel or thin client deployment, in any of our architecture documents. Instead, specific architecture documents for the productization shall describe such deployments in detail.

References

C4 modeling PlantUML C4 extension for PlantUML

Architecture Review Checklist

Mon, 01 Jan 0001 00:00:00 +0000

Architecture review checklist for pull requests in Markdown.

Architecture review Markdown template

Traceability is important throughout the entire development process. To simplify traceability for architectural review, use the following template when reviewing via pull requests. The template is the checklist translated into markdown format.

- [ ] Is the content updated according to all relevant input requirements?
- [ ] Is the described functionality in accordance with relevant input Architecture Specifications?
- [ ] Are all _major_ software/hardware components identified and their relevant interfaces defined?
- [ ] Does the architecture specification have the right level of abstraction?
- [ ] Is the functional decomposition well described?
- [ ] Is the dynamic behavior well described?
- [ ] Is the information model described?
- [ ] Is the deployment described?
- [ ] Are architecture decisions described?
- [ ] Do all entities in the architecture have consistent names?

---

Are sufficiently precise (i.e. sufficient quantity to be useful) descriptions put on:

- [ ] a) compatibility
- [ ] b) standard compliance
- [ ] c) availability
- [ ] d) configuration
- [ ] e) assumptions and dependencies

---

- [ ] Is all mitigation of risks described in the threat model covered?
- [ ] Is the architecture considering best practices?
- [ ] Is the architecture feasible for refinement to a functional design (Description of Function)?
- [ ] Is reuse of existing trusted and verified software modules/libraries considered?
- [ ] If applicable, is the architecture structured so that reuse is possible for other components or products?

Azure DevOps template

Pull request template assists a review when performing the review. When using Azure DevOps, the markdown template can be used as a pull request template. Copy the markdown template content into a markdown file at this location in the architecture code repository:

.azuredevops\pull_request_template\architecture review.md

For more details regarding templates in Azure DevOps, see Improve pull request descriptions using templates.

Clang-tidy

Mon, 01 Jan 0001 00:00:00 +0000

Clang-tidy is an LLVM native C/C++ static code analysis tool that can be used locally and on a build server. It can be integrated in Visual Studio 2019, or run from the command line.

Where to find the tool

Visual Studio 2019 contains Clang which can be included from the Visual Studio Installer. In Visual Studio Installer, choose to modify the Visual Studio installation and choose the optional individual component “Clang compiler for Windows”.

LLVM has to be installed in a separate step. Inside Visual Studio 2019, open Settings in the Clang Power Tools toolbar. Open LLVM and download or add the existing LLVM version.

If not using Visual Studio 2019, clang-tidy can be installed with the LLVM installer which can be downloaded from https://releases.llvm.org/download.html. If another installation path than the default C:\Program Files\LLVM is used, manually add the <misc path>\LLVM\bin to the environment variable PATH.

Description

The purpose of clang-tidy is to provide an extensible framework for diagnosing and fixing typical programming errors, like style violations, interface misuse, or bugs that can be deduced via static analysis. Clang-tidy is modular and provides a convenient interface for writing new checks.

Clang format is a C++ code formatting tool that can be used to automatically format the code. It is also part of LLVM.

Motivation

Clang-tidy is easy to use with Visual Studio, and the issues can be found during the coding. Clang-tidy supports the C++ standards C++98, C++11, C++14, C++17 and partially C++20, which give a good support for static code analysis on modern C++ code.

It contains a feature for fixing up erroneous code, clang-tidy-fix.

Clang format helps to format the code.

How to analyze the code

In Visual Studio 2019 there is a ‘Clang Power Tools’ toolbar, with buttons for Tidy, Tidy-Fix, Format, etc. The analysis is made on a single file.

A complete project or Visual Studio solution must be analyzed from the command line.

New and changed code

A Clang-tidy analysis of a product or Visual Studio solution includes new, changed, and old code. Hence all issues found by the enabled checkers must be handled.

Existing codebase

It is not possible to baseline the existing code base when performing a Clang analysis.

New versions

New versions can be installed using the Visual Studio Installer or LLVM installer.

A tool responsible needs to inspect the release notes to find new and changed checkers, and build locally to inspect the impact on the codebase. The tool responsible can adjust the rules to fit with the current code style, remove rules that cause too many false positives to be useful, or solve the issues in the code.

Also, current deviations can be reviewed to check if the new version might handle the code better for false positives. When the new version works as intended locally, the build servers can be updated with the new version.

Ruleset

Storage

The rule set is stored in one or several configuration files together with the code, e.g. in a git repo. A configuration file placed on the top source code folder of the project covers all code that has no local configuration.

If a local configuration file is placed on the top folder of a part of the code base, all code placed under that folder will use the local configuration file instead. If no local configuration file is found, a traverse up in the folder structure is made to find the closest configuration file.

Version control

One or several configuration files are placed and version-controlled together with the code, .clang-tidy is used for the rules and .clang-format is used for the formatting.

Add/remove rules

Rules (checkers) are modified, added, and removed by changing the .clang-tidy file. The methodology is to enable big scopes/groups like cppcoreguidelines-* (checks related to C++ Core Guidelines) and then to disable specific checkers -cppcoreguidelines-macro-usage (finds macro usage that is considered problematic because better language constructs exist for the task).

Example for disabling one check-in a group in .clang-tidy:

Checks: 'cppcoreguidelines-*, -cppcoreguidelines-macro-usage'

Some checkers have extra settings in the form of key-value-pairs. For example, the number of allowed lines in a function can be set. The actual number of lines can be set as extra information, in this case, value = 108 lines.

Example:

 - key: readability-function-size.LineThreshold
 value: 108

New rule set from new tool version

When a new version of the tool has been provided, the configuration files should be updated with a comment containing the new clang version. The pull request should be reviewed by the code responsible.

Standards

Clang is not compliant with any specific security standards.

Monitoring

When running Clang-tidy in Visual Studio, issues are displayed in the ‘Error List’ view. When running from the command line, the errors are displayed in the output log. A pull-request in Azure DevOps can be set up with a required Clang-tidy check that blocks the pull-request from completing while there are unhandled clang errors in the code.

Example of the result from a pull-request, with a clang-tidy error:

MyClass.cpp:344:56: error: the parameter 'myString' is copied for each invocation but only used as a const reference; consider making it a const reference [performance-unnecessary-value-param,-warnings-as-errors]
void MyClass::SomeFunction(std::string myString)
 ^
 const &

Severity levels

Clang-tidy has the severity levels: error, warning, and remark. It is recommended to fix errors and warnings, which can be achieved by enabling the clang-tidy build option --warnings-as-errors.

How to handle deviations

Suppressions of Clang-tidy issues are handled as comments in the source code. Either with NOLINT or NOLINTNEXTLINE comments. A descriptive comment on why suppression is needed must be added.

There can be false positives where the code constructs are not understood by the tool. The default action should always be to rewrite the code to mitigate clang-tidy issues. But sometimes it is necessary to deviate and then the suppression is code reviewed like any other change going into the codebase.

Example of how to silent a clang-tidy checker for one function:

 // Silent specified diagnostics as it makes no sense to divide function.
 // NOLINTNEXTLINE(readability-function-size)
 NcpResult SomeFunction(const std::string& myString)
 {
 ... //too many lines in the function
 }

Code Review Guideline

Mon, 01 Jan 0001 00:00:00 +0000

A code review intends to improve the quality of the code. Someone other than the author of the code performs the examination.

Code Review Goals

Eliminate bugs at an early stage
Improve code quality
Increasing knowledge about the project
Learning from each other
Ensure that the story is fully implemented from a functional and technical point of view
Improve existing and new code
Verify the correctness of both code and unit testing

Code Review Rules

You may not approve your own changes
Offer as much positive feedback as possible
Review everything that can be read
It is a great place to learn something new
Find out whether your comment meets any goal. Comments that don’t provide any value are really demotivating. Consider whether your change proposition really does matter
Try to understand why such a solution has been applied instead of writing that the code is wrong. You don’t have to be always right, and a comment should be the beginning of a discussion, not just a change
Try to coach the author
If some part is missing, describe what should be added, e.g., what more needs to be changed, what unit tests need to be added
Explanations and discussion results should be noted either in the code comment, in the commit description, or in the implementation details design description
Automate as much as possible by introducing static code analysis tools
Do not make a merge to the master branch until the code review is completed
Proposed changes in functionality should be discussed and stored in separate work items. If the change is handled as part of future work, please add the corresponding work item

Code Review Checklist

Check that the code implements the intended design (check the applicable design/architecture description)
Check that the code complies to coding rules not checked by static code analysis
Check that the code implements or follows the applicable mitigations described in the threat model
Look for possible automated tests, and if they are available, review them
Look for potential bugs
Check if all errors are handled gracefully
Check if code is implemented efficiently, e.g.:
- Do not contain duplicates
- Patterns and design principles are properly used
Check if the code introduces technical debt
Check if the code does not cause side effects
Check code readability
- Is the code easy to understand for later maintenance if the need arises
- Do method and variable names express what they are used for
Check if code is properly commented - is it difficult to understand parts or hacks should always be commented on to help other people understand the reason for the implementation
Check if all comments are addressed before merging to the master branch
Check Coding standards

How to run Code Review

There are at least four types of code reviews. Below is a short description of each one.

Formal inspections

Formal reviews are usually called “inspections” from Michael Fagan’s seminal 1976 study at IBM regarding the efficacy of peer reviews. He tried many combinations of variables and came up with a procedure for reviewing up to 250 lines of source code. After 800 iterations, Fagan came up with a formalized inspection strategy named “Fagan Inspection.”

In general, a formal review refers to a process review with three to six participants meeting together in one room with printouts and/or a projector. Someone is the “moderator” or “controller” and acts as the organizer, keeps everyone on task, controls the pace of the review, and acts as an arbiter of disputes. Everyone reads through the materials beforehand to properly prepare for the meeting.

When defects are discovered in a formal review, they are usually recorded in detail.

Over-the-shoulder reviews

This is the most common and informal of code reviews. An “over-the-shoulder” review is just a developer standing over the author’s workstation while the author walks the reviewer through a set of code changes. Typically, the author drives the review by sitting at the keyboard and mouse, opening various files, pointing out the changes, and explaining why it was done this way.

E-mail pass-around reviews

This is the second-most common form of informal code review and the technique preferred by most open-source projects. Whole files or changes are packaged by the author and sent to reviewers via e-mail. Reviewers examine the files, ask questions and discuss with the author and other developers, and suggest changes.

The hardest part of the e-mail pass-around is in finding and collecting the files under review.

Tool-Assisted reviews

This refers to any process where specialized tools are used in all aspects of the review: collecting files, transmitting and displaying files, commentary, and defects among all participants, collecting metrics, and giving managers some control over the workflow.

Pair Programming

Pair programming is a development process that incorporates continuous code review. Pair programming is two developers writing code at a single workstation with only one developer typing at a time and continuous free-form discussion and review.

Studies of pair programming have shown it to be very effective at finding bugs and promoting knowledge transfer.

References

How to add a code review checklist to your pull request Pull request template

Code Review Guideline

Mon, 01 Jan 0001 00:00:00 +0000

A code review intends to improve the quality of the code. Someone other than the author of the code performs the examination.

Code Review Goals

Eliminate bugs at an early stage
Improve code quality
Increasing knowledge about the project
Learning from each other
Ensure that the story is fully implemented from a functional and technical point of view
Improve existing and new code
Verify the correctness of both code and unit testing

Code Review Rules

You may not approve your own changes
Offer as much positive feedback as possible
Review everything that can be read
It is a great place to learn something new
Find out whether your comment meets any goal. Comments that don’t provide any value are really demotivating. Consider whether your change proposition really does matter
Try to understand why such a solution has been applied instead of writing that the code is wrong. You don’t have to be always right, and a comment should be the beginning of a discussion, not just a change
Try to coach the author
If some part is missing, describe what should be added, e.g., what more needs to be changed, what unit tests need to be added
Explanations and discussion results should be noted either in the code comment, in the commit description, or in the implementation details design description
Automate as much as possible by introducing static code analysis tools
Do not make a merge to the master branch until the code review is completed
Proposed changes in functionality should be discussed and stored in separate work items. If the change is handled as part of future work, please add the corresponding work item

Code Review Checklist

Check that the code implements the intended design (check the applicable design/architecture description)
Check that the code complies to coding rules not checked by static code analysis
Check that the code implements or follows the applicable mitigations described in the threat model
Look for possible automated tests, and if they are available, review them
Look for potential bugs
Check if all errors are handled gracefully
Check if code is implemented efficiently, e.g.:
- Do not contain duplicates
- Patterns and design principles are properly used
Check if the code introduces technical debt
Check if the code does not cause side effects
Check code readability
- Is the code easy to understand for later maintenance if the need arises
- Do method and variable names express what they are used for
Check if code is properly commented - is it difficult to understand parts or hacks should always be commented on to help other people understand the reason for the implementation
Check if all comments are addressed before merging to the master branch
Check Coding standards

How to run Code Review

There are at least four types of code reviews. Below is a short description of each one.

Formal inspections

When defects are discovered in a formal review, they are usually recorded in detail.

Over-the-shoulder reviews

E-mail pass-around reviews

The hardest part of the e-mail pass-around is in finding and collecting the files under review.

Tool-Assisted reviews

Pair Programming

Studies of pair programming have shown it to be very effective at finding bugs and promoting knowledge transfer.

References

How to add a code review checklist to your pull request Pull request template

Color Guide for Azure DevOps

Mon, 01 Jan 0001 00:00:00 +0000

Recommendations of colors for dashboards and graphs in Azure DevOps.

The key objectives of this guideline are to:

ensure consistent look and feel of dashboards and graphs.
avoid misunderstandings during SteCo meetings and when sharing information with various stakeholders.
facilitate and enable efficient comparison of dashboards and graphs from different projects/streams.

A general common sense approach should be applied:

Something considered “good” or ”completed” should be green, e.g., WI state = Closed, etc.
Something considered “bad” or ”open” should be red, e.g., WI state = Open, Severity = Critical etc.

ELSP R&D quality dashboards

Colors used for graphs based on state

Colors used for graphs based on severity

Azure DevOps dashboards

To follow the general common sense approach applied, the following colors are recommended to be used in the Azure DevOps dashboard and graphs.

Colors used for graphs based on state (always sort by label –> ascending):

Colors used for graphs based on severity (always sort by label –> ascending):

Note

The colors that are already set/changed in the Azure DevOps dashboards and charts will be reset to defaults every time you change the query behind them, a possible workaround is to tick off “Select folder to copy dashboard queries” while creating a copy of dashboard and then just update newly created queries.

MS Office charts and graphs

To follow the general common-sense approach applied, the following colors are recommended to be used in MS Office charts/graphs:

Colors used for graphs based on state (always sort by label –> ascending):

Colors used for graphs based on severity (always sort by label –> ascending):

Component Capabilities Guideline

Mon, 01 Jan 0001 00:00:00 +0000

This is a guideline describing the most basic parts of Component Capabilities. Specific add-ons, e.g. to ensure safety compliance may be needed in the future.

What and not How

Component Capabilities shall describe what the component “can do” for anyone who wants to understand what the component is capable of. The capabilities should be described in a short format focusing on the “what”, while the “how” is defined in architecture and detailed design documentation.

Bullet lists are a common format in a Component Capabilities file since they usually list all supported functionality shortly and concisely.

The current state of implemented and verified functionality

Capabilities serve as internal documentation of what a component can do in its current state. Future feature support should not be written in a Component Capability.

Only verified functionality should be stated in a Component Capability. Hence, only when the functionality is tested, the Component Capability updates can be merged.

Before closing a feature, the newly implemented functionality shall be documented in the corresponding Component Capabilities file.

Input and consumers

Input to a Component capability is a feature description and the feature acceptance criteria. Examples of consumers of a Component Capability are developers for reference, new employees, testers, product owners, and architects.

Component Capabilities may also serve as input to Product Capabilities and end-user documentation.

Traceability, reviewers, location, and filename

The Component Capabilities are documented in a .md file named “Capabilities.md”, located in the repository of the component source code.

This file lives with the component lifecycle, and when new features are added for a specific component version, the capability files must be updated based on the corresponding version of the component repository.

When the Component Capability is updated, it should be merged with a pull request linked to the feature or any of its child work items. This will provide enough traceability from the Component Capability perspective. In other words, by linking the pull request to the feature or any of its child items, the capability update can be fully traced towards the entire chain of System Requirements – Epics – Features – User Stories – Tasks – source code, and the related test cases.

The pull request including the Component Capabilities update should be reviewed by the Product Owner.

There is no direct traceability link between Component Capabilities to threat models. However, there will be a traceability path between threat models and Component Capabilities when there are references to features or bugs from the threat models.

Architecture design and detailed design documentation have no explicit traceability to Component Capabilities. The relationship between Component Capabilities and architecture and detailed design descriptions is only realized through features being defined with architecture and detailed design descriptions as input.

Pull request in Git repositories corresponds to check-in in Team Foundation Version Control (TFVC) repositories.

What is not a Component Capability

A Component Capability is not a product requirement, it’s written as the output/outcome of the implementation. As input to implementation, System Epics, Epics, and Features will be used (these work items are replacing the previously used product requirements). See the workflow visualization below for a better understanding.
A Component Capability should not be confused with architecture or detailed design documentation. Component Capabilities are written as the outcome of implemented and tested features or bug corrections, and these work items were in an earlier step potentially defined with architecture and detailed design documentation as input.
SDK documentation is not part of Component Capabilities.
In general, unsupported functionality should not be mentioned in a Component Capability. However, exceptions can be made if it helps the reader to understand the current state of the product.

Workflow diagram

References

Example of a Component Capability (AC800M Compiler Component Capabilities) Component Capabilities template

Component Capability Template

Mon, 01 Jan 0001 00:00:00 +0000

Component capability markdown template.

Markdown template

Copy the contents to an empty markdown file and start editing. Remove the help text in block quotes and any unused sections.

# \<Component name\> capabilities
---

# Table of contents

1. [General component purpose and overview](#introduction)
2. [Capabilities](#capabilities)
 2.1. [Subchapters of different Component capabilities](#subcapability)

## 1. General component purpose and overview <a id="introduction"></a>

Describe briefly the purpose of the component. If possible and if it makes understanding easier, end-user use case diagrams may be included (optional).

## 2. Capabilities <a name="capabilities"></a>

Description of capabilities, potentially divided into sub-chapters. For a detailed guideline to the content of this chapter, see [Component Capability Guideline](http://abb-is-000650.nmea.abb.com/pcp2/docs/guides/Conceptual-Guides/Component-Capability-Guideline/).

### 2.1 Subchapters of different Component capabilities <a name="subcapability"></a>

Component Dynamic Behavior Template

Mon, 01 Jan 0001 00:00:00 +0000

Dynamic behavior template for components.

dynamic_behavior.md

Copy the contents to an empty markdown file and start editing. Remove the help text in block quotes and any unused sections.

# Dynamic Behavior for ComponentName {#DynamicBehavior_ComponentName}

<!-- This template is to be used to describe the dynamic behavior of a component, it shows how the component behaves for important use cases. It shall be used together with the main markdown file describing the complete component. -->

---

<!-- List of different behaviors with sequence diagrams or activity diagrams -->

## Dynamic Behavior Title1

<!-- Textual description for the behavior. -->
Behavior description...

```plantuml
@startuml
!include dynamic_behavior_sequence.puml
@enduml
```

## Dynamic Behavior Title2

<!-- Textual description for the behavior. -->
Behavior description...

```plantuml
@startuml
!include dynamic_behavior_activity.puml
@enduml
```

The “!include dynamic_behavior_activity.puml” above don’t work in an ADO Wiki. You have to convert the .puml to a .png and include it in the markdown. It may work in Visual Studio with the right plugins - but it doesn’t help much if it is visualized with the ADO Wiki.

dynamic_behavior_sequence.puml

Copy the text to an empty plantuml file and start editing.

@startuml

skinparam sequence {
 ArrowColor Black
 ActorBorderColor Black
 ParticipantBorderColor Black
 LifeLineBorderColor Black
 BoxBorderColor Black
}

skinparam note {
 BorderColor Black
 BackgroundColor AliceBlue
}

participant Client
box "Platform1"
participant "Object1:Class1" AS Obj1
participant "Object2:Class1" as Obj2
end box
participant "Class2" AS Class2
participant "Class3:Interface1" AS IF1

loop cyclic execution.
Client -> Class2: Get()
activate Class2
Class2 -> IF1: Get()
activate IF1
IF1 --> Class2: data
deactivate IF1
== Initial data retrieved, \
create all objects that are not already created. ==
loop for each property
Class2 -> Obj1: Method1()
alt New Request
Class2 -> Obj2**: Create()
note right
Note text with extra description.
end note
end /'end alt New Request'/
end /'end loop for each property'/
destroy Class2
end /'end loop cyclic execution'/

@enduml

dynamic_behavior_activity.puml

Copy the text to an empty plantuml file and start editing.

@startuml

<style>
activityDiagram {
 BorderColor black

 diamond {
 LineColor black
 }
 arrow {
 }
 partition {
 LineColor black
 }
 note {
 FontColor Blue
 LineColor Navy
 BackgroundColor #ccf
 }
}
document {
 BackgroundColor transparent
}
</style>

title Template example
start
:ClickServlet.handleRequest();
:new page;
if (Page.onSecurityCheck) then (true)
 :Page.onInit();
 note left: Init the page
 if (isForward?) then (no)
 :Process controls;
 if (continue processing?) then (no)
 stop
 endif

 if (isPost?) then (yes)
 :Page.onPost();
 else (no)
 :Page.onGet();
 endif
 :Page.onRender();
 endif
else (false)
endif

if (do redirect?) then (yes)
 :redirect process;
else
 if (do forward?) then (yes)
 :Forward request;
 else (no)
 :Render page template;
 endif
endif

stop
@enduml

Configure Access Matrix for Replication User

Mon, 01 Jan 0001 00:00:00 +0000

In the example below is a description of needed access rights for a user (or AD group) to be able to use OpsHub to replicate work items between collections/organizations.

I have used the ABB AD group “PCP_Work_Replica_U_Access_group” and assigned the needed access to that group in the below example. The service account user has been added as a member of that group.

If new organizations or collections need to be added I suggest that the above AD group is given needed access and not a user directly.

For replication projects “write” access (the one described below) is only done (and needed) to replica project “that gets new workitems created or edited” and "read" access when only “fetching” workitems.

This means that if OpsHub will only “read” workitems from a project only Read access is needed.

Below settings are only needed when OpsHub needs to update/create work items in the project.

For the new service user/AD groups, the following “five” (5) permissions are required for OpsHub replication to migrate and integrate with work items:

When configuration is related to “Project settings --> …” then this step needs to be done for all projects that will be replicated

Configuration for Azure DevOps Services

1. User/group needs to be added in all projects that are currently being migrated or integrated

Done in: organization settings --> users --> group rules

2. Bypass rules on the work item updates (Required for user impersonation)

Done in: Project settings --> Security

3. Create and Edit work items

Will be solved by steps in 1 + 4 as that will give partial Contributor rights.

4. Area and Iteration (This allows to check and create area paths and iteration paths)

Create child nodes
Edit nodes

Done in: Project settings --> Project configuration -->Iterations --> Security

Areas --> Security -->

If you break the inheritance rule for access you need to consider that and give explicit access rights for those areas/iterations.

5. “Create tag definition” is also needed.

Configuration for Azure DevOps Server

1. Access permission 1

Added PCP_Work_Replica_U_Access_group to AD group OCS_Collection_Readers as OCS_Collection_Readers was a member of Readers in the targeted Azure project. (ABB-PA-CommonComponents-Replica in OCS collection)

2. Access permissions 2, 3, 4, and 5

(Access permission 5 change isn’t showing in the picture below, but please look at Service configuration bullet 2 as the same value will be used)

Data Discipline Dashboard

Mon, 01 Jan 0001 00:00:00 +0000

The quality dashboard can help teams measure and compare product quality by setting appropriate widgets and queries. A common template based on standardized queries will help save effort and improve efficiency. By setting appropriate widgets and queries, the quality dashboard can help teams measure and compare product quality. A template based on standardized queries helps save effort and improve efficiency.

This guide sets a standard data discipline dashboard template in Azure DevOps (ADO) and guides how to customize it for a project.

Intended for

Quality control managers, release owners, and product owners.

Introduction

The data discipline dashboard is a built-in quality practice that is part of the quality dashboard. It aims to help development teams check the data quality of work items by themselves and further improve the transparency and accuracy of the dashboard for key performance indicators (KPIs).

Layout

Structure

Type	Widgets
General	a. Missing data. Epics/features/bugs are active but without description/effort / acceptance criteria. b. Unplanned and Unassigned. Epics/features/bugs are active but not planned or assigned; Epics no target date. c. Parent-child hierachy issue. Active features without parents; Active bugs without requirements; Active epics/features/bugs with closed parent but open child. d. Open items in old iteration path. Epics/features/bugs are active but delayed in old path; Active epics in wrong area path. e. DoD or DoR not completed. Uncompleted DoD or DoR.
Project scope	a. Epics scope. Epics at G2; Epics added after G2; Epics removed after G2. b.Scope bugs. Scope bugs; Deferred bugs.
Bug handling	a. Missing data of bugs. Open bugs without repro / How found / Severity / Found in / SIL / Function / Integrated build; Open bugs critical high/regression. b. Bug aging. Bugs added in 1 month; Bugs closed in 1 month; Open bugs older than one PI.

Color standard

Color	Green	Yellow	Red	Blue
Number of work items	0	1-10	>10	Not relevant (as a baseline).
Examples

People & Frequency

People involved	Roles
Creator	Release owner, scrum master, configuration manager, development team.
User	Development team.
Frequency of use	Checking the data discipline dashboard once a week is recommended.
Supervisor	Quality control manager, release owner.

How to create and edit a dashboard

Copy this template to create a new dashboard for a project. Choose “Copy Dashboard”.

Fill in the information about the new dashboard here. Choose “Project Dashboard” in the “Dashboard Type” part. A project dashboard can involve different teams.

The related queries are automatically copied when copying the dashboard. These queries can then be reused.

It is also possible to customize the dashboard by editing widgets. The data discipline dashboard mainly involves two kinds of widgets: Markdown and Query tile.

Markdown

Markdown is a lightweight markup language. It adds simple formatting elements to the text, keeping the text readable in any text editor.

In the data discipline dashboard, Markdown can be used to show some basic information about the project, like names of the project, categories, explanations, etc.

Select “Configure” to edit the Markdown. You can change the width and length of the Markdown, and add also the text.

Learn more about Markdown in Tutorial: Markdown in ADO.

Query tile

Query tile is a configurable tile that displays the summary of shared query results. From the configuration dialog, select either a team favorite or a shared query. Rules can also be specified to change the query tile color based on the number of work items returned by the query.

In below dashboard, query tiles can be used to visualize the data status. Different colors show different urgency degrees.

Select “Configure” to edit the query tile. It’s possible to change the title, query, and the color standard.

To edit the query, click the widget and then choose “Editor”.

Learn more about queries in Define a work item query in Azure Boards.

Query criteria

Example 1: Open bugs regression

This query can select open regression bugs.

Field	Operator	Value
Work Item Type	=	Bug
State	<>	Removed
State	<>	Closed
Area Path	Under	“Team Project Name”\”Stream”\”Product/platform”[\”Major Product/platform Version”\”Target Product/platform Release”]
Regression	=	True

Example 2: Scope bugs

If a bug is found during the development of a release and the change control board (CCB) decides to fix it in a later version, the bug is deferred. When a deferred bug is planned for a future release, it will be considered a scope bug for that release.

This query is designed to select open-scope bugs.

Field	Operator	Value
Work Item Type	=	Bug
State	=	Any
Area Path	Under	“Team Project Name”\”Stream”\”Product/platform”[\”Major Product/platform Version”\”Target Product/platform Release”]
ScopeBug	=	True

Example 3: Scope change after G2

Epics are often created before G2 and already exist in the backlog. Epics can be added after G2 either as a consequence of a change request of a system requirement, a split of a large epic into two smaller epics, or a new enabler epic. Epics needs to be collected at the G2 date to set a baseline. Use a query to catch all epics added to the project scope after G2. Also, some new/active epics are moved to other area paths after G2. The epics that have been added and removed return identical values.

If other work item types are needed for the project scope, it’s possible to add more query tiles to monitor the progress. This involves three queries:

Query 1: Epics at G2

Create a baseline based on all the IDs of epics at G2.

Field Operator Value

Work Item Type = Epic

State = Any

ID In all the Epics IDs at G2

Tips: How to select all the IDs of epics at G2 There are many different ways to create a baseline. For example, you can use Excel.

First, use a query to screen out all the epics at G2. Then export these epics to Excel. Finally, use the “Textjoin” formula to get all the IDs, and then copy these IDs back to ADO as a baseline.

Query 2: Epics added after G2

Make a query based on IDs to catch if any epics were added after G2.

Field	Operator	Value
Work Item Type	=	Epic
State	<>	Removed
Area Path	Under	“Team Project Name”\”Stream”\”Product/platform”[\”Major Product/platform Version”\”Target Product/platform Release”]
ID	Not In	All the IDs of Epics at G2

Query 3: Epics removed after G2

Make a query based on IDs to catch if any epics were removed after G2.

Field	Operator	Value
Work Item Type	=	Epic
State	=	Any
Area Path	Not Under	“Team Project Name”\”Stream”\”Product/platform”[\”Major Product/platform Version”\”Target Product/platform Release”]
ID	In	All the IDs of Epics at G2

References

Quality and KPIs DoR and DoD Tutorial: Markdown in ADO How-to Work With Epics and Features Define a work item query in Azure Boards Query by titles, IDs, and rich-text fields in Azure Boards and Azure DevOps

Describe the Usage of SCA Tool Template

Mon, 01 Jan 0001 00:00:00 +0000

When a new static code analysis (SCA) tool has been chosen for a product or part of a product, it needs to be described to facilitate its use in the considered and other products.

This template contains the information that should be part of the documentation for each SCA tool. See Static Code Analysis Tools for recommended tools.


## Where to find the tool

(There shall be a description of where to find the tool, how to install it locally if applicable, and/or where to find it on a server.)

## Description

(Add a short description of the tool and its usage. Can it perform static or dynamic analysis? Does it support the formatting of the code? Which programming languages are supported?)

### Motivation

(What is the reason for choosing this tool in general or for a specific product?)

### How to analyze the code

(Describe how to perform the analysis in general. Describe how to handle 3rd-party code.)

### New and changed code

(Describe how to analyze new and changed code. Describe which rules can be skipped for which codebase, and which rules must be handled.)

### Existing code base

(Describe how to handle an existing code base; if it is possible to baseline issues on the existing code base, and only focus on new issues on added or changed code. Describe the baselined rules for each code base and the rules that must be handled.)

## New versions

(Describe how to update the tool with a new version. Also, mention who is responsible for performing the update.)

## Ruleset

(Describe how the ruleset configuration works in the tool. Consider the following subchapters:)

### Storage

(Describe where the ruleset can be found, e.g. is it a part of the code as a configuration file, or stored on a server?)

### Version control

(Describe how to handle different versions of a ruleset. It must be possible to know exactly which rules have been used for a specific version of a product. A configuration file placed with the code is one way of handling versioning, another way is to have a separate document under version control listing the rules.)

### Add/remove rules

(Describe how to change the ruleset to add and remove rules.)

### New rule set from new tool version.

(Describe how to update the ruleset when a new version of the tool has been provided. Also, mention who is responsible for updating the ruleset.)

### Standards

(Describe if the tool can be mapped to for instance security rules to support security standards, e.g. to be compliant with IEC 62443-4-1.)

## Monitoring

(Describe how the issues found by the tool are monitored, how to detect new issues, how to find already handled and remaining issues, and how to display the severity of not handled issues. Is it possible to integrate the tool in the existing development environment, for instance, Azure DevOps?)

## Severity levels

(Describe the different severity levels of the issues for a specific tool. Some tools like SonarQube have different types of issues (bug, vulnerability, and code smell) and different severities (blocker, critical, major, minor, info). Klocwork only uses severity (critical, error, warning, review).)

## How to handle deviations

(Describe how to handle false positives and deviations from relevant and correct issues. How and where to add motivation for deviation.)

DoD for L4 Bugs

Mon, 01 Jan 0001 00:00:00 +0000

The definition of done (DoD) for L4 bugs are the checks performed when an L4 bug is considered completed.

The product owner and L4 coordinator are responsible for L4 bugs, and the DoD helps them assess the completeness. DoD needs to be fulfilled before a bug is no longer considered an L4 bug.

What is an L4 bug?

An L4 bug is a customer problem escalated to L4/R&D by support level 3 using a bug in Azure DevOps (ADO).

Then it can only be considered as such if:

A customer is suffering from it.
A solution or workaround has not been identified.
The problem is related to a released product (G5 passed).
The issue is not considered by R&D as product enhancement request .

Please, note that following issues are not considered L4 bugs:

Issues coming from pilot projects (since such issues are linked to products not released).
Documentation issues related to L4 bugs, raised by L3 Support in relation to an L3 case management (this can happen if L3 Support close a case with a configuration change and later open a new work item to suggest a documentation change to better describe the configuration, based on the L3 case closure experience).

DoD for L4 bugs

There are two alternative ways for an L4 bug to fulfill DoD:

An investigation has been done, so that:

CCB has enough information to decide whether the bug should be corrected (not yet necessarily decided in which version) or not.
A product issue number (PIN) has been generated and added to the bug if applicable.
L3 has enough information (from an R&D perspective) to de-escalate the corresponding Salesforce case.

The Salesforce case is closed (the customer has a workaround etc.) after an L4 bug has been created by L3.

When the DoD is verified, the bug will cease to be an L4 bug and continue as a regular bug. It will no longer be part of the L4 backlog or statistics.

L4 bug identification

L4 bugs can be identified when the following conditions are satisfied:

The bug is linked to at least one Salesforce case.
The bug is not categorized as enhancement.
The bug is not a clone of another bug.
The status of the bug indicates that initial investigation is not completed and/or a CCB decision is to be taken.

The “External Reference” field, which is a part of the Standard Bug Template, contains the link between the bug raised in ADO (L4 bug) and Salesforce (customer) case. Then, if the same issue is suffered by many customers there will be a single ADO item linked to many Salesforce cases.

L4 bug age count

Age count for L4 bugs:

Begins when one of the following conditions is satisfied:
- The bug is created by L3 as L4 bug.
- An existing bug (not L4 bug) is linked by L3 to a Salesforce case and become an L4 bug

Ends when one of the following conditions is satisfied:
- The bug is closed as “Copied to Backlog” and cloned to the targeted release proposed to the customer (see How to Handle Deferred Bugs).
- The bug status indicates that the investigation is complete and a CCB decision has been made. If a targeted release has already been assigned (e.g. started as an internal bug and was later linked to a Salesforce case by L3, becoming an L4 bug) this status will reflect that.
- Bug is resolved with a workaround or a configuration change (information provided, to be verified on site).
- Bug is closed as rejected.

NOTE: Refer to How to Handle Bugs in Multiple Releases if the bug must be addressed in multiple release (e.g. a TC is requested and the fix will also be included in the next release). Please note that this will not affect the age count.

dod system epic

Mon, 01 Jan 0001 00:00:00 +0000

Confirm epics are completed
System integration tests (SIT) have passed
Required documentation is reviewed and approved
The result is demonstrated and accepted by PPM

Definition of Ready and Definition of Done

Mon, 01 Jan 0001 00:00:00 +0000

The “Definition of Ready” (DoR) are the checks performed when a system epic, epic, feature, story, or bug is defined and ready to start work on. The “Definition of Done” (DoD) is the checks performed when the work items are completed before it is closed.

The Product Owner, Architect, and Scrum Master are responsible for system epics, epics, features, stories, and bugs – and the DoR/DoD helps them to assess the readiness and completeness.

General Rule

Never start working on something that is not Ready
Never stop working on something that is not Done

System epics, epics, features, and stories are secured by both acceptance criteria and DoD. Both need to be fulfilled before closing the work item.

The difference between the DoD and the acceptance criteria is that acceptance criteria are unique for an individual work item, resulting in test cases while the DoD is generic and the same checks are applied to each work item type including the acceptance criteria.

DoR and DoD for work items

System-Epic

Definition of Ready

Functional: The title/description/acceptance criteria come from an approved system requirement
Enabler/Architectural: Understandable title, description and acceptance criteria
An initial breakdown into epics involving streams
The system epic backlog shall be ranked for the target release
Area path set

Definition of Done

Confirm epics are completed
System integration tests (SIT) have passed
Required documentation is reviewed and approved
The result is demonstrated and accepted by PPM

Epic

Definition of Ready

Understandable Title and Description
Testable acceptance criteria established
If/how to demo defined
Effort estimated
Link to System Epic
Dependencies to other Epics defined
Preliminary stream architecture
Draft features
The area and iteration path is set
Security impact considered
The epic is ranked in the backlog
Epic reviewed

Definition of Done

All child features are closed
All product integration tests (PIT) passed, and existing bugs have CCB decision
Product-level documentation approved
Epic demonstrated
Input to end-user documentation and release notes provided
Installation/delivery package updated

Feature

Definition of Ready

Understandable Title and Description
Testable acceptance criteria established
If/how to demo defined
The feature is estimated to ensure it can be completed in an increment
Preliminary design ready
Draft user stories
Link to Epic
Dependencies on other features defined
The area and iteration path is set
Security impact considered
The feature is ranked in the backlog

Definition of Done

All child stories are closed
All unit and component tests passed
Component documentation approved
Demo performed (or planned)

Story

Definition of Ready

The story is clarified and accepted.
Enough information is provided to be able to start task breakdown by the teams.
The story is estimated to ensure it can be completed in a sprint.
Acceptance criteria are provided and agreed upon.
The story/enabler is aligned with the architecture.

Definition of Done

Confirm tasks are completed.
Impact on architecture, design, and interfaces identified and updated.
Code reviewed and issues fixed.
Static Code Analysis is performed, and issues are fixed.
Unit tests passed and included in the automated test environment.
Cumulative unit and functional regression tests passed.
End-user documentation is updated.
The story fulfills the acceptance criteria.

Bug

Definition of Ready¹⁾

Is sufficient information available to evaluate the bug (e.g., images, dumps, log files)?
Can the problem be reproduced?
Are severity, priority, and security effect assigned?

Definition of Done

Is the code reviewed and issues fixed?
Is the static code analysis performed and issues fixed?
Is the user documentation, including release notes, updated?
Is the architecture and design documentation updated?
For security-critical components and security-relevant bugs, are the threat models, attack surface and criticality analysis, and the security assessment updated?
Are the unit, functional, and/or security tests updated and passed?
Are other similar issues identified?
Are bugs created for other affected products or product versions?

¹⁾ The bug is “ready” when the investigation can start

How to work with DoD/DoR

Adaption of DoD/DoR

Based on the context and needs for a stream the DoR and DoD might need to be tailored.
Consider the context when adapting the DoR/DoD (HW, SW, FW, Embedded, HMI, DevOps, standards, etc.).
Ensure that the adapted version is documented and communicate the changes to all members and stakeholders.
Analyze results in retrospectives and refine the DoR/DoD as the streams and teams mature.
The “Head of Development” and “Head of Quality” approve the adaptations of the DoR/DoD – to make sure mandatory checks are included.

DoR/DoD when Appgami not integrated

If the Appgami plug-in is not integrated into the collection, the DoR/DoD information needs to be added to the work item differently. There are some options:

add the DoR/DoD checklist to the “description” field
add it in the “validation” field (if present)
use the “discussion” field

For the “description”/“validation” fields, the DoR/DoD can be added to a template in ADO to reduce manual work.

DoR/DoD in Cloud Azure DevOps

The DoR/DoD can be added to cloud Azure DevOps by Appgami for epics, features, stories and bugs in the information field.

The “ready” criteria can be added to the “Definition of Ready” area by choosing a proper template from Appgami.
- The criteria could be customized inside the project team based on their product development.
- The progress and status could be tracked by checking the criteria one by one.
The “done” criteria can also be the “Definition of Done” area by choosing a proper template from Appgami.
- The criteria could be customized inside the project team based on their product development.
- The sum of all “done” checks above progress corresponds to the recommended “Definition of Done”.
The teams check the boxes in the DoR/DoD information field before the epic/feature/story is moved to “Active” or ‘Completed" in ADO.

If a DoR / DoD is “Not Applicable” it shall be agreed with relevant stakeholders (PO/RO/Dev Team) and marked as “SKIPPED” (see example below)

IMPORTANT: When “SKIPPED” is applied the criteria must be marked so that the DoD can be closed. (Reach 100%)

DoR:

DoD:

Discipline Dashboard in Azure DevOps

Azure DevOps support setting up Dashboards to check the work items (e.g. for orphans, fields not filled in, etc.). The dashboards give an overview of a set of work items and can be combined with the Appgami checklists.

The Discipline Dashboards in Azure DevOps are indicators of some of the checks in a DoD/DoR.
Use the Discipline Dashboards to regularly monitor issues with the epics, features, and stories, and take action on deviations.

References

ELSP R&D Quality Dashboards

Mon, 01 Jan 0001 00:00:00 +0000

R&D quality dashboards can be automatically created, based on Azure DevOps (ADO) data, to support the organization in visualizing project progress based on quality key performance indicators (KPIs).

Intended for

The quality dashboards provide valuable support to release owners, quality control managers (QCMs), and product owners during meetings.

Useful info and links

For terminology and KPI descriptions, refer to the legend page on respective dashboard (or use the direct links below).

Project Progress KPIs description Bug Management KPIs description Tests KPIs description Full Business Analysis documentation

Dashboard access

Access is provided for all ELSP employees who are part of this AD group.
In case of any issues with access, please contact Piotr Salamon.

Data upload schedule

Automatic data upload (from ADO and Team Foundation Server (TFS)) is scheduled daily at 2 AM CET. The update process, including refreshed dashboards, takes about 1.5 hours and is completed at 4 AM CET.

Projects/releases adding/updating

Contact the respective QCM to add a new release/project setup or to modify the existing one.

Naming convention

Release names in “Dictionary” should follow the general pattern which is specific for a given solution described below:

800xA 6.2
800xA 6.2 - AV
800xA 7.0
800xA x.y - xyz
S+ Phoenix

Tips & tricks

There must be parent/child links between epics and features to make the project progress dashboard work. Additionally, effort and target dates should be filled in in epics and features in ADO/TFS.
“Project start date” on ConfigApp should be the same as the G2 date (the date when full release scope is committed).
All new setups and changes are implemented during the next daily data upload (at 2-4 AM CET).
When using a specific area path for deferred bugs, that area path must also be added in the “Product” bugs configuration (this may also be required in scope/introduced bugs configuration).
When configuring the area path for deferred, an “and” to “state closed / reason deferred” is required.
The “deferred” must rely on state (closed) and reason (deferred) to differentiate from open bugs. The configuration cannot rely solely on tags, iteration path, or others to define deferred bugs.
Project progress dashboard works appropriately only for work items (epics & features) using standard templates. Teams using customized work item templates are encouraged to move to the recommended ones.

Current issues/limitations

If you face the issue while pasting a value, e.g., for a given area path, you may not be able to select it. The workaround is to choose any other area path, then paste the copied one again, and it will work.

Currently, the test dashboard is limited to test plans coming from TFS only. The issue has been raised to Microsoft and is under investigation/fixing.

This is a completely new functionality, internally developed and intensively tested. However, we understand that there may be undiscovered issues or difficulties due to a lack of descriptions or guidelines. In this case please contact: Piotr Salamon.

References

Project Progress & Bug management demo recording Test and ConfigApp demo recording ConfigApp PCP R&D Quality Dashboards PCP R&D Quality Criteria

How-to Adopt Standard Work Item Templates

Mon, 01 Jan 0001 00:00:00 +0000

An existing Azure DevOps (ADO) project - on-premises or in the cloud - may differ from the current standard PCP work item templates due to historical reasons or tailoring. This guide lists the steps and tools to adopt standard work item templates in an existing ADO project with existing data.

Note: ADO templates are complex. Do not hesitate to contact the CM process team or community for expert support and knowledge sharing if needed.

Intended for

Configuration managers.

Activities

Due to differences intechnology, the activities to adopt standard templates are executed in different ways in ADO Server (on-prem) and ADO Services (cloud). Therefore, specific instructions are provided for each activity where applicable.

Spot the differences

Identify differences between the current project and the standard template (with support from the quality control manager (QCM) or CM team if needed).

Tips and tricks: The CM team periodically runs a script based on ADO REST API to analyze current templates and export a csv file containing the list of field differences for each collection, project, and work item type.

Decide how to reconcile differences

Apply the strategies below to manage typical template differences (with support from the QCM or CM team if needed).

Difference	Strategies
Missing fields	This is the most typical case. When a new field is added to the standard template, add it to the project template using the standard template as a reference. The new field will be visible in existing work item data, with empty or default values depending on the field definition.
Different work item names	Introduce the new work item type in the project with matching fields. Change the work item type of existing data with REST API or bulk editing from a query. Reconfigure the backlog configuration to show the new work item type name if applicable (e.g. “Product Requirement” -> “Feature”).
Additional fields	Desired additional fields can remain unchanged. Unused ones may be hidden, and their value may be copied to “Description” in historical data.
Different state names	Update the state machine and backlog visualization configuration. Bulk update existing data.
Different drop-down lists	Update the template. Bulk update existing data if any values are removed or renamed.
Different rules	Update rules.

Create a work item in the OpEx project to request the template change.

Tips and tricks: In some cases, the difference analysis may trigger process change requests to improve the standard template.

Prepare the updated template

The CM team prepares the updated template according to the following:

Where

How to

On-prem

Edit the xml template of the corresponding project in the Configuration Management repo on a new branch. Copy/paste and adapt the layout as needed from the on-prem standard work item template stored in the same repo.
Import the template to a validation project in the same organization.
Create a pull request describing the change and assign it to the respective ADO project configuration manager for review.

Cloud

If the ADO organization uses the standard template without modifications, import the latest published standard template from the Configuration Management repo. Assign this template to a validation project for review.
If the organization uses a modified template, the CM team cannot import it directly. The project’s configuration manager needs to create a copy of the current process in the web UI, apply the change and assign the updated template to a validation project for review.

(Optional) If the change requires a bulk update of existing data, prepare a validation project with the same template as the project to update. Add some data, either by importing it from the original project with Naked Agility Migration Tools or by creating sample data.
Update the template in the validation project. Do not change anything in production until the change is validated.
(Optional) If the change requires a bulk update of existing data, simulate the bulk update using Naked Agility Migration Tools.

At the end of this activity, the updated project template is available for review in a validation project and/or as code.

Review the change

Review the updated template (with support from the QCM or other roles if needed):

Check if the template works in the validation project.
Review and complete pull request (on-prem only).

Update in production

After informing the users and selecting an agreed-upon time, the CM team should update the ADO template in production. If required, bulk update the existing data with Naked Agility Migration Tools. This step requires no downtime.

Where	How to
Cloud	Apply the template to the project from the web UI.
On-prem	Apply the template to the project using a Witadmin-based script (also, in the Configuration Management repo)

Use one or more of the following methods to inform users about changes in a template applied to a project:

Publish a banner in respective ADO organization with a description of the update.
Email or other notification to key people.

Details

About work item template updates

On-prem and cloud templates are updated differently. For this, refer to the instructions in the Configuration Management repo, which contains standard templates.

Bulk edit of existing work items

To bulk update work items after a change, write a configuration file for Naked Agility Migration Tools to update data as decided and try it in the validation project until it is validated. Multiple rounds of simulation may be required. It is a good practice to ask some users to check the transformation in the validation project.

Tips and tricks:

Examples and experience are available within the CM community to support this step.
Store the configuration file(s) and the templates in a repo to be able to repeat the process as it was validated.

Motivation to align templates

Aligning project templates with the standard ADO template is crucial for maintaining process consistency and enabling the calculation of key performance indicators (KPIs).

Here are some scenarios that require a change in the ADO template or existing data:

Adopting fields that are used in QMS processes, e.g. “Cloned” and “Security Relevant”.
Changing the list of allowed values for a field, e.g. “How Found”.
Changing the state names, e.g. from “Proposed” to “New”.
Migrating a project from on-prem (e.g. tfsa.abb.com) to cloud (e.g. dev.azure.com/ABB-BCI-PCP).
Bulk editing field values to match standard field values.

Configuration as code approach

The process for adopting standard work item templates in projects follows a configuration-as-code approach, ensuring consistency, traceability, and efficiency. All templates are managed as code and stored under source control in a Git repository for each project or set of projects sharing the same template. This allows for version control and traceability of changes to specific process change requests.

An automated pipeline with multiple stages is used to deploy the templates. Initially, the templates are deployed to a validation project. After successful testing and review, they are then deployed to the production environment. Manual changes in the production environment are strictly prohibited to maintain consistency and traceability.

The CM team drives the execution of changes, with the support the CM community as needed for executing or reviewing changes. Whenever possible, at least one of the configuration managers of a project is involved in the review and approval for that project. Since changes are reviewed as code, any conflicts in names or layout are resolved before applying the template to production, ensuring smooth and conflict-free deployments.

This centralized approach is more efficient than the previous decentralized method, although it requires effort to manage and maintain. Priorities are managed to optimize the use of available resources, ensuring that changes are addressed promptly. The process includes tracking where changes have been applied and where they have not, which was not possible with the previous approach.

For safety projects

Safety projects are managed according to this process, but can be stored in a separate repository in an appropriate location approved by the Safety team. This approach ensures consistent application of templates across all projects on-premises, provides clear traceability of changes, improves efficiency through centralized management and automated deployment, resolves conflicts before deployment, optimizes resource usage, tracks changes, ensures compliance for safety projects, allows for historical tracking and rollback, eliminates manual errors, and provides a clear audit trail for all changes made.

Tools

The main tool used to manage existing data for this process is Naked Agility Migration Tools. It is a very powerful tool. This guide’s most relevant feature is the ability to migrate and bulk update work items while maintaining their history.

Examples:

Copy work items from the production project to a validation project.
Bulk edit the value of a field to a default value.
Map values to bulk replace them.
Add a tag.
If a field has a certain value, set the value of another field as configured.

Q&A

Q: Who initiates the process of adopting standard work item templates in a project? A: The process is usually initiated by the CM team when a standard work item template is updated or by the Quality team when an ADO project deviates from the standard template (for example when a necessary field to follow a QMS process or to calculate a KPI is missing).

Q: My project was created using the Scrum template. Do I have to change it to use the Agile template? A: No, you can update to the Agile template with the same work item types, states, and backlog visualization.

Q: Is it allowed to have additional custom fields? A: Additional custom fields are allowed to store more information, provided that the QMS or approved tailored processes are followed.

Q: Who is responsible for applying standard templates in ADO Services (cloud)? A: The CM team applies standard templates to https://dev.azure.com/ABB-BCI-PCP and makes templates available that can be imported to other organizations.

Q: Who is responsible for applying standard templates in ADO Server (on-prem)? A: The CM team prepares template implementation for each on-prem project and submits a pull review to each project’s configuration manager. After successful completion of the pull request, the CM team applies templates to projects. Considering the effort, the CM team may take help from the CM community.

How-to Handle Software Vulnerabilities

Mon, 01 Jan 0001 00:00:00 +0000

This guide describes the process for handling software vulnerabilities in products within PCP R&D. It includes instructions on everything from recording a description of a reported issue to documenting and communicating its remediation.

A software vulnerability can be detected in many different ways, which impacts what steps to take in this process according to the following:

An external party, e.g. researcher, government organization, or customer (also ABB internal), reports a vulnerability in, or malware targeting, a PCP offering and expects a vulnerability handling process. See examples of communication of such incidents under Cyber security alerts and notifications.
- The full process from first response to notification shall be followed.
An external party, e.g. researcher or customer (also ABB internal) reports a problem (e.g. a support case concerning a bug) but doesn’t identify it as a vulnerability. If the problem turns out to be a vulnerability:
- Sync with the ABB product security incident response team (PSIRT) ( cybersecurity@ch.abb.com) to create a unique ID (CVE ID) for this vulnerability.
- Start the process at “Confirmation of vulnerability”, under Initial triage.
A vulnerability is discovered, typically internally within PCP, and there is no specific reporter to interact with. If the problem turns out to be a vulnerability:
- Follow the bug management process, see How-to Manage Bugs.
- If it’s helpful for the customer(s), a field communications should be considered, see 3BUL980146 Writing and Publishing Field Communications.
It is discovered that malware is affecting a PCP offering and there is no specific reporter to interact with.
- Sync with ABB PSIRT ( cybersecurity@ch.abb.com) to create a unique ID (CVE ID) for this vulnerability.
- Start the process at “Confirmation of vulnerability”, under Initial triage.

Note: The ending of the process may differ depending on the life cycle status of the involved product(s):

For products in the “Active” and “Classic” states, the expectation is normally that software vulnerabilities are corrected.

For products in the “Limited” or “Obsolete” states, this will be determined on a case-by-case basis. One, but not the only, possible decision is to issue a cyber security advisory about the problem, but not to correct it.

Intended for

Product managers, product owners, cyber security engineers, and L4 coordinators.

Prerequisites

When a vulnerability is identified and reported to ABB the first point of contact is the PCP head of cyber security.

PCP head of cyber security appoints a lead person for the subsequent handling of the vulnerability, referred to as the vulnerability handling lead (VHL). This person will ensure that the vulnerability is handled according to this process. In the 9ADB005047 ABB Software Vulnerability Report, the person shall be entered as the “ABB lead”.

Activities

Below flowchart with time requirements follows the ABB Software Vulnerability Handling Policy. The timelines are communicated externally and shall be considered customer commitments.

First response

Responsible role: VHL.

Acknowledge receipt of the vulnerability report. This only applies when the vulnerability is reported from an external source. Security issues can also be identified from internal sources like product development, product tests, or L3 Support.
Route vulnerability details to the appropriate product development team.
Sync with the ABB Product Security Incident Response team ( cybersecurity@ch.abb.com) to create a unique ID (CVE ID) for this vulnerability.
Create the ABB Software Vulnerability Report, complete section 1, and add an entry in the cyber security core team’s list of vulnerability handling cases. This report will follow the case until closed. Its document number does not need to be related to the document number of the security advisory. The ABB Software Vulnerability Report is recommended to be stored where the product team stores the other documents related to the case, preferably in OnePCP DMS.
Notify Group Cyber Security Council (GCSC).

Initial triage

Responsible role: Product owner for the concerned product(s)/system. The cyber security engineer for the concerned product(s)/system assists and shall at least be consulted.

Create a bug in ADO for concerned products (can be one or several products). See also Bug Classification about security tagging of bugs. Add a reference in the ABB Software Vulnerability Report.
Try to reproduce the vulnerability, if not possible try to get more information from the reporting source.
Sync with the VHL, who should update the fields related to initial triage in the ABB Software Vulnerability Report.

The possible results are:

Confirmation of vulnerability.
Rejection, the first analysis gives that this is not a security issue, i.e. a false positive.
The reported issue is not relevant for PCP (products), forward it to the responsible unit. Involve the VHL for further advice. If the reported issue is in another PCP product, forward it to the responsible product via the VHL.

Investigation

Responsible role: Product owner for the concerned product(s)/system. The cyber security engineer for the concerned product(s)/system assists and shall at least be consulted.

Follow the defined bug management process described in How-to Manage Bugs.
- Fill in the “Effect” field under “Security Analysis” as described in the Bug Classification guide.
- Calculate the CVSS score (see FIRST’s Common Vulnerability Scoring System calculator) and fill in the “CVSS” field under “Security Analysis”.
- Determine which product(s) is affected and the level of severity.
- Determine the root cause and all affected versions.
- Effort estimation and impact analysis for fix.
- Consider if the same or similar vulnerability may exist in other functions or products and if so, create defects for those.
- The product owner and product manager determine possible releases that should include the fix.
Sync with the VHL who should updatee the fields related to investigating in the ABB Software Vulnerability Report.
Decide on potential further actions together with the VHL.
Notify GCSC via the VHL.

Remediation

Responsible role: Product owner for the concerned product(s)/system. The cyber security engineer for the concerned product(s)/system is responsible for the security advisory/notification.

Follow the defined defect process for fixing the bug and plan for the remediation in agreement with the VHL.
- Identify if a workaround exists that can be used temporarily until the solution can be released.
- Implement the solution (if the workaround is not sufficient).
- Create a “security advisory” with details about the vulnerability and remediation. The security advisory is a field communication category that is described in 3BUL980146 Writing and Publishing Field Communications. See also the 3BSE071315 Cyber Security Advisory template.
- If the vulnerability is in a 3rd-party product or in the environment where the ABB product operates or has a dependency, a 2PAA124139 Cyber Security Notification may be created.
- Consider performing an analysis of the root cause to identify why the vulnerability was introduced, why it was not identified by the security development lifecycle process, and whether this process needs to be improved. For more information and guidance about root cause analysis, see 2PAA2024-115317 Root Cause Analysis.
The VHL updates the fields related to remediation in the ABB Software Vulnerability Report and notifies GCSC.

Notification

Responsible role: Product owner for the concerned product(s)/system.

Distribute solutions or workaround to customers along with a security advisory as described in Writing and Publishing Field Communications.
The VHL updates the fields related to the notification state in the ABB Software Vulnerability Report.
Report to GCSC using the ABB Software Vulnerability Report.
If decided by the extended review team (defined in Writing and Publishing Field Communications), make public disclosure at https://global.abb/group/en/technology/cyber-security/alerts-and-notifications.
The ABB Software Vulnerability Report should be reviewed and approved by the PCP Cyber Security Core team when the case is closed.

Details

Confidentiality of vulnerability information

9AAD126846 Information Classification and Handling Standard describes that “lists of vulnerabilities in systems” shall be handled as “Confidential information”.

All departments involved in the vulnerability handling process should understand the sensitivity of the information involved and protect it accordingly. Information should only be transferred or disseminated to those with the need to know.

Sensitive customer information should be protected in transit and storage. Detailed information about vulnerabilities that affect customers should not be stored on insecure SharePoint sites or file shares.

The access control provided by ADO and OnePCP DMS is considered to be sufficient. Users who have access to the ADO and OnePCP DMS also have access to security information in cases related to vulnerabilities.

References

How-to Perform Threat Modeling

Mon, 01 Jan 0001 00:00:00 +0000

Threat modeling is the process of analyzing various business and technical requirements of a system identifying the potential threats, the mitigations of these threats, and documenting the vulnerabilities these threats have on the system.

Note: Threat modeling isn’t a one-time activity. It needs to be repeated in increments and iterations and checked at specific milestones during product development.

The purpose of this guide is to explain how to create and maintain a threat model in an agile way, and how to ensure that the threat model is ready at release.

It walks through the activities to be executed in each increment. For more information on how to compose the threat model, see 3BSE070612 Threat Modeling Guideline.

Intended for

Architects, cyber security engineers, software developers, test engineers, and product owners.

Activities

Plan threat modeling activities

Threat modeling is a part of the agile development process, and it shall be planned and performed in each increment. During planning for the next increment, development and architecture teams shall check if planned design changes may affect the existing threat model or if input from other sources indicates an update is needed. If this is the case, plan for the threat model revisions accordingly.

The threat model updates are transparently planned in Azure DevOps (ADO) as features (enablers) and added to the stream backlogs. Ideally, each increment should have its own features defined to ensure that the threat model is independently checked, whether any changes are required or not.

The architects identify the threat model requests based on changes in the architecture, and the cyber security engineers identify requests based on design changes.

Update threat model

In general, involved people shall create and maintain the threat model using the recommended threat modeling tools (Microsoft Threat Modeling tool is highly suggested). Publish the threat model on the ADO wiki to make it visible and accessible to the teams.

Note: Each development stream shall have its own architecture documentation in ADO wiki (preferred) or GitHub. The threat modeling section on the wiki must be up-to-date with the latest available threat modeling diagram.

Document the components that make up your system. A clearly documented model of your entire application simplifies the analysis. Note down use cases, data flows, data schemas, and deployment diagrams.

There are two types of visualizations you can build:

Data flow diagram (mandatory): It depicts how data is designed to move through your system. It shows the operational level and displays where data enters and exits each component, data stores, processes, interactions, and trust boundaries.
Process flow diagram (optional): At an application level, it depicts how users interact and move through various use cases.

While data flow diagrams focus on how your system works internally, process flow diagrams concentrate on user and third-party interactions with your system.

Identify the most important actors and assets in the threat model diagrams.

Review threat model

Review the threat model on the ADO wiki. Check the validity and correctness of the updated threat model, and align the model with the architecture documentation and related software components.

Use pull requests to capture any review comments or further updates.

The cyber security engineer moderates the review and makes the final approval of the updates.

Evaluate threats

Based on the threat model, identify which one of the assets can be compromised by potential attackers.

For example, use a STRIDE checklist (spoofing identity, tampering with data, repudiation threats, information disclosure, denial of service, and elevation of privilege) for the dataflows that cross a trust boundary.

Keep the list of the identified threats and vulnerabilities together with the threat model.

If changes in the threat model highlight new findings (not known from the previous cycle), these need to be investigated.

Once the threats are identified, you have a master list or library of threats associated with each asset, its operations, and a list of possible attacker profiles. Analyze which of these threats are applicable to your modeled component/product) and identify proper mitigations in order to reduce the likelihood of the threat (from “High” to “Medium” or “Low”).

Make an initial ranking of which threats that need to be mitigated or not.

Resolve threats (or identify mitigations)

When threats are evaluated, mitigations need to be identified to reduce the likelihood of the threat. The evaluation of the effectiveness of the mitigation requires to identify and accept a certain level of risk, in case the threat occurs, based on the impact on the product.

From National Institute of Standards and Technology (NIST): “The risk is a measure of the extent to which an entity is threatened by a potential circumstance or event and is typically a function of the adverse impacts that would arise if the circumstance or event occurs and the likelihood of occurrence”.

The risk assessment addresses the potential adverse impacts to ABB systems and assets, see 3BSE070612 Threat Modeling Guideline).

Based on the risk analysis of the threats, you can deal with the vulnerabilities in the following ways:

Don’t do anything (risk accepted).
Remove the feature associated with it.
Turn the feature off or reduce the functionality.
Make code, infrastructure, architecture, or design fixes.

Enter the vulnerabilities that need to be addressed in ADO (to be included in increments or iterations). Tag them as “security” bugs and track them to closure.

Note: In case the risk is ‘not acceptable’ and no solutions can be applied, the head of cyber security or the cyber security product manager shall be involved for final approval.

Validate threats (or validate mitigations)

Mitigations shall be individually validated, by proper test cases defined for them, and the result approved by cyber security engineer.

Validate (for example in tests) the threats and vulnerabilities that are addressed. Make sure the threat modeling is completed (that features/enablers are closed), the prioritized threats are analyzed, and the vulnerabilities (bugs) are addressed.

You need to decide the steps for any remaining threats and if they should be included in upcoming updates of the threat model.

Details

About threats and vulnerabilities

A threat exploits a vulnerability and can damage or destroy an asset. A vulnerability refers to a weakness in your hardware, software, or procedures.

According to NIST, a threat is any circumstance or event with the potential to adversely impact organizational operations (including mission, functions, image, or reputation), organizational assets, or individuals through an information system via unauthorized access, destruction, disclosure, modification of information, and/or denial of service.

References

How-to Setup a Team in ADO

Mon, 01 Jan 0001 00:00:00 +0000

Defining a team in Azure DevOps (ADO) allows the use of planning and visualization features, for example, the team backlog, sprints, capacity planning, boards, and team dashboard.

This guide describes how to request a new team and how to create, configure, and update it.

Intended for

Configuration managers, scrum masters, product owners, and anyone involved in requesting and updating teams in ADO.

Prerequisites

The team creation procedure requires ADO project administrator access. It can be performed by a configuration manager with access (not all of them have project administrator access, especially in ADO projects shared by many teams or multiple streams) or by the IS ADO support team through a ticket in ServiceNow.

In both cases, requests and approvals are fully tracked. IS has an always up-to-date knowledge base to identify the right configuration manager to ask for approval.

Activities

Request a new team

Any team member can request a new team. The following information is needed:

Collection URL.
Project name.
Team name.
Team description (optional).
List of initial team members:
- 1 or 2 team admins (typically scrum master and product owner).
- Other team members (optional, they can be added later by team admins).
Backlog iteration: by default “Team Project Name” \ “Stream” [\ “Product Line”] \ “Teams” \ “Team Name”.
Backlog area: by default “Team Project Name” \ “Stream”.
Query folder: by default “Team Project Name” \ “Stream” [\ “Product Line”] "Teams" \ “Team Name”.

There are two ways to request a new team – through an IS ticket or an Issue work item in ADO.

The configuration manager selects one or both ways and provides guidance and training to the new team as needed.

Request a new team through an IS ticket

Use the request type User Access Management - Azure DevOps Global in MyServices:

IS then requests approval of the team from the configuration manager.

Request a new team in ADO

Create a team creation request through an “Issue” work item in ADO. The work item is then assigned to the configuration manager.

Team creation and approval

The configuration manager reviews the request(s) and ensures that:

The team, team members, admins, etc. are defined with associated permissions.
The backlogs, iterations, etc. are configured with associated permissions.
The query folder is created with associated permissions.

The configuration manager approves the request(s) and creates the new team.

Team Updates

Once the initial team creation and configuration are complete, the team admins – typically the scrum master and/or the product owner – can perform routine updates, for example:

Adding or removing team members.
Creating and selecting iterations to be displayed as sprints.
Adding sub-areas.
Configuring board styles.
Configuring team notifications.

For further information, see Microsoft’s guide on Manage and configure team tools.

Details

ADO team updates FAQ

After a team has been created and configured, who can add or remove team members? A team administrator, typically a scrum master or product owner, can add or remove team members (or update the team administrators). It is not necessary to ask a project admin or IS.

For further information, see Microsoft’s guide on Add users or groups to a team.

I have access to ADO, and I am a member of a team, but I cannot see the team’s repos and wiki. What to do?

If you don’t see the git-based wiki, and you don’t see the repo’s menu, it means that you have no license, you are accessing ADO as a stakeholder.

Open an IS ticket “User Access Management - Azure DevOps Global”. Usually, the ticket is opened by your line manager, functional manager, or scrum master.

If you have a Visual Studio (MSDN) subscription, request access as a Visual Studio subscriber and provide a screenshot of the license from the Visual Studio portal.
If you have no license, request a “Basic Access” level.

In the IS ticket, specify that you have access to ADO and you need to change the access level to be able to see the wiki.

For further details, see Microsoft’s information About access levels.

How-to Work with Epics and Features

Mon, 01 Jan 0001 00:00:00 +0000

The purpose of this guide is to provide hands-on support to the roles involved in defining the requirements in PCP R&D QMS captured in system epics, epics, features, and user stories.

As background to this guide, there is a conceptual guide - Agile Requirement Structure - focusing on the big picture.

Epics, features, and user stories include both requirements and planning content. This guide focuses on the requirement part – for more details on planning, prioritization, and follow-up, see the master process.

Intended for

Product owners, architects, scrum masters, and other roles with interest in the different requirement levels such as release owners and product managers.

Overview

Work item hierarchy as below (every work item can have many children but only one parent). Other work items like document updates and bugs will later (when ready) be connected to the hierarchy.

System epic
- Epic
  - Feature
    - User story (will be defined later)
      - Task (not included, not defined as a requirement)

System epic

System (and technological) requirements are defined in Decision Focus (DFN) for release planning. See Portfolio and Product Management’s process description for details:

Managing Market Requirements and System Requirements - Process Description

A system epic is used to represent such a requirement for implementation planning and follow-up within R&D. The technical content of a system epic is automatically replicated from the system requirements. All the work needed by different streams and teams for such a requirement shall be linked to the corresponding system epic.

A system epic is also used to provide enablers for project/release specific activities, such as gates and release maintenance, architectural work, and other technical enabling efforts like setting up a test framework.

The system epic can span over several increments and can be implemented by one or several streams but must be finalized in the defined release. The priority of a system epic should relate to the target release priority and technical dependencies with other system epics.

The system epic overview / life cycle can be described as:

Figure 1. Epic states

Figure: System epic states

New

The system epics related to system requirement, and business type, are automatically initiated and technical content (title/description/acceptance criteria/…) is replicated from the system requirement. Further information, like involved streams, is documented by a product manager, (system) product owner, or (system) release owner.

System epics of type enabler/architectural are fully described by a (system) product owner, (system) release owner, or (system) architect to provide a parent work item for all work needed towards a specific requirement, project/release activity or architectural investigation/conclusion or other type of enabler.

The quality of the preparation is controlled by the definition of ready (DoR).

System Epic template

The following fields are mandatory (in bold):

The title is a short name that provides understanding and context.
The assigned to should be set to a relevant responsible person to follow up on the requirement/activity.
The state shall be set to “New”. For state changes see the Work Item State Description guide.
The area path should be set to the targeted release.
The iteration path should initially be set to “Planning”, and when a first walk-through of the system epic has been performed an estimation in which increment it can be completed should be set.
Details
- For business type, the field shall include a link to the DFN system requirement.
- For architecture type, it shall include detailed information of what should be completed, and “acceptance criteria” to verify the fulfillment. Limitations should be defined in the form of “not included”.
SR description, includes information replicated from DFN.
SR details, includes information replicated from DFN.
Classification/Type, should be set to proper value depending on the type of system epic.
- Business – system or technical requirements.
- Architecture – architectural investigations (an enabler related to architecture)
- Enabler - project/release specific activities (refactor, upgrade, gate handling etc.)
Related work
- Make links to epics (child), and consider the different types: architecture, development, enabler, UX, and test.
- It is also recommended to make links to related system epics (e.g. dependencies). Theses dependencies can be within the same release or to other streams and product lines. Examples: Impacts to Harmony Connectivity for 800xA, Or, NG development customizations for 800xA, Symphony Plus, Freelance.
In addition, some fields are not mandatory, e.g. priority, risk, and business value.

DoR for a system epic Before the implementation of a system epic is started the DoR shall be fulfilled. See also related details in the DoR DoD Guideline.

Functional: The title/description/acceptance criteria come from an approved system requirement
Enabler/Architectural: Understandable title, description and acceptance criteria
An initial breakdown into epics involving streams
The system epic backlog shall be ranked for the target release
Area path set

Active

Implementation of a system epic includes:

When DoR is met and the first child is set to “Active”, the state is set to “Active” by the (system) product owner.
Continuous refinement meetings to refine epics and potentially reprioritize.
Follow up on progress – remove impediments.
When all development-related work items (architecture and development) are completed, the (system) product owner sets the system epic to “Resolved”.

Resolved

Test of system epic System integration test cases to verify the system epics shall be developed in parallel with the implementation of epics. Input to the test cases is the system epic acceptance criteria. Typically, these tests are automated. To be able to follow up on the system epic test activities an epic under the system epic should be created. When all work has finished with a system epic and all underlying features are set to “Closed” (see feature description) the system product owner / architect goes through the definition of done (DoD). For details about system epic testing, see the System Test Overview guide.

DoD for the system epic Before a system epic can be set to state “Closed” the DoD must be checked:

Confirm epics are completed
System integration tests (SIT) have passed
Required documentation is reviewed and approved
The result is demonstrated and accepted by PPM

The (system) product owner or architect reviews the DoD, sets the system epic to “Closed”, and informs key stakeholders (e.g. release owner, product manager, system product owner, quality control manager, architect, test lead).

Closed

After DoD is fulfilled, the state can be set to “Closed”, thereafter the system epic will not be maintained.

Removed

The “Removed” state shall be used when a system requirement has been removed from DFN (business) or when an architectural system epic is canceled. In the case of a requirement is moved from one release to another the iteration path shall be updated according to the new release destination. If the system epic has been initiated, in the state “Active”, the state shall be moved back to “New”.

Epic

Epics are defined as vertical slices of the product with end-user value as the main perspective. When defining an epic, one should think about how the completion of the epic improves the end-user experience.

In addition to the epics that realize customer value (defined as “Business” in the classification field, see below) there are two other categories of epics. One that enables the business epics or the infrastructure needed (defined as “Enabler” in the classification field). Examples of enabler epics are refactoring, test system/setup, pipeline infrastructure, OS updates, and PLM system work. The third category is “Architectural” which is dedicated to architectural efforts.

An epic must fit the release but can span several increments. An epic can be implemented by one or several teams depending on team setup (e.g. usage of cross-functional teams).

Epic overview / Life cycle

Figure 1. Epic states

New

Epics are initiated by the product owner or architect to implement the system epic. Epics for system epic breakdown and customer use case definitions (classification “Business”) are defined by the product owners under alignment with all necessary stakeholders (typically with product managers, architects, scrum masters, and developers). The priority of the epic is given by system epic priority or by technical dependencies.

In the state “New”, the epics are detailed by the product owner or architect with support from other stakeholders. The quality of the epic definition in this phase is controlled by the DoR, but in essence, the epic should contain all the information necessary to understand how it should be implemented. This includes the identification of the different underlying features. Remember to consider more than the development-oriented features. Features related to architecture, enabler, UX, and test should be considered.

Epic template

The epic template is not the same for the different streams – please use the guide as it makes sense to your context.

The following fields are mandatory (in bold):

The epic title is a short name that provides understanding and context.
The epic description shall contain a “story” and if/how the epic shall be demonstrated. To clarify the scope and avoid “gold plating”, define limitations in the form of “not included” (limitations can be related to functionality, operating systems, services, etc.). Initial ideas on implementation should be documented under “details” with text or links to other material, e.g. an implementation proposal.
The epic acceptance criteria define what must be met and verified for epic acceptance, preferably documented in Gherkin syntax: Given <initial context> When <event> Then <expected outcome>, this will ensure clear definitions and also support test case automation.

If system epics don’t exist in your Azure DevOps (ADO) template then links to system requirements and related epics can be included in the description. If you want to have a more elaborate epic description there is an example in the appendix.

Figure 2. Epic description

Example of a software epic description:

Figure 3. Software epic example

Example of a hardware epic description:

Figure 4. Hardware epic example

Path

Area path in which release will the epic be delivered.
Iteration path in which increment will the epic be ready? When an epic is under preparation this field can be left empty, but it shall be filled out no later than it is set to “Active”.

Effort estimate

High-level estimate of the epic in hours. This is the first rough estimate that will be updated when the features are defined and estimated. A recommendation is to start with a t-shirt comparison and if possible, some further refinement. Optionally the product owner / architect can involve development teams and carry out a more thorough estimation by applying planning poker or other techniques.

Size	Hours	Comment (An epic can be implemented by one or several teams)
XS	500	e.g. 2-3 persons in 7 weeks
S	1000	e.g. 2-3 persons in 13 weeks or 4-6 persons in 7 weeks
M	2500	e.g. 4 persons in 20 weeks or 6-8 persons in 7 weeks
L	5000	e.g. 6 persons in 26 weeks or 8-9 persons for 18 weeks
XL	7500 - Consider splitting	e.g. 6-7 persons in 39 weeks or 9-10 persons for 26 weeks

Example: This epic is slightly larger than a “medium”, so 3000 hours could be a relevant estimate.

Classification

Value area

Architectural = Architecture work (An enabler related to architecture)
Business = Implementing a system requirement.
Enabler = Solving an enabling technical matter (refactor, upgrade, etc.).

Security relevant Consider if it is likely that work will affect a security-critical component, as listed (already or to be) in the security criticality analysis, modify a component’s attack surface, or is the work in some other way security-relevant (this may motivate a revised criticality analysis). Some examples are modifications in functionality for authentication, access control, integrity checking, encryption, or protection measures for denial of service (DoS) attacks.

Details can be found in the Security Criticality Analysis guide.

True = Epic is security relevant.
False = Epic is NOT security relevant.

Related work

Make a link to system epic (parent).
Make links to features (child), and consider the different types: architecture, development, enabler, UX, and test.
It is also recommended to make links to related epics (e.g. dependencies, within release or to other streams) If these dependencies impact implementation order use (predecessor) or (successor )

All epics shall be linked to a system epic, for new enabler epics a new system epic might be needed.

In addition, some fields are not mandatory, e.g. priority, risk, business value, time criticality, and start/target date.

DoR for an epic

Before the implementation of an epic is started the DoR shall be fulfilled. See also related details in the DoR DoD Guideline.

Understandable Title and Description
Testable acceptance criteria established
If/how to demo defined
Effort estimated
Link to System Epic
Dependencies to other Epics defined
Preliminary stream architecture
Draft features
The area and iteration path is set
Security impact considered
The epic is ranked in the backlog
Epic reviewed

The product owner or architect reviews the epic’s DoR with participants according to RACI for epics (RACI for epics can be found here).

Note that for the RACI roles, (R) drives the meeting, (C) needs to either attend the meeting or provide written comments (“no comments” is of course also ok), while (A) and (I) are invited as optional and do not have to attend or provide comments.

If someone is important for the review but not covered by the RACI, they should of course be invited as well.

If it is approved, check the box “Review DoR” and add a note in the discussion field with the conclusion of the review (including any important note if relevant) and the name of the participants. One review meeting can of course cover many epics.

If an epic is not subject to review of DoR, the reason shall be noted in the discussion.

Active

Implementation of epic

When implementation starts the state is set to “Active”, and if not yet set, the iteration path must be defined in ADO by the product owner / architect.
Continuous refinement meetings to refine epics and potentially reprioritize.
Follow up on progress – remove impediments.
When all development-related work items (architecture and development) are completed the product owner sets the epic to “Resolved”.

If the epic needs to be paused (e.g. due to changed product manager priorities, delayed delivery of dependent functionality, or unveiled technical uncertainties) the epic shall be:

Set the epic to “New” with the reason “Implementation halted”.
Update iteration path to agreed new iteration or without defined iteration if it is not yet set.
In the discussion field, elaborate on the reason to pause and describe how far the work has proceeded.
Ensure that linked child work items, not yet closed, have been managed in the same way.
Ensure that dependent epics are informed.

Resolved

Test of epic

Product integration test cases to verify the epics shall be developed in parallel with the implementation of features. Input to the test cases is the epic acceptance criteria. Typically, these tests are automated and include relevant hardware. To be able to follow up on the epic test activities a feature under the epic should be created. When all work has finished with an epic and all underlying features are set to “Closed” (see feature description) the product owner / architect goes through the DoD.

For details about epic testing see the Product Test Overview guide.

DoD for the epic

Before an epic can be set to state “Closed” the following work must be done.

All child features are closed
All product integration tests (PIT) passed, and existing bugs have CCB decision
Product-level documentation approved
Epic demonstrated
Input to end-user documentation and release notes provided
Installation/delivery package updated

The product owner or architect reviews the DoD sets the epic to “Closed” and informs key stakeholders (e.g. release owner, product manager, product owner, quality control manager, architect, test lead).

Closed

After closure, the epic will not be maintained.

Feature

Features are a further breakdown of the epic into more details than expressed in the epic. They describe what needs to be implemented in the system in order to realize the epic. Since epics can be of business/architecture the feature follows the same classification.

Feature overview / Lifecycle

The following chapters will describe each step in the feature lifecycle. See the overview of the “feature states” in the figure below. When a feature is submitted, its state is automatically set to “New”. In this state, the feature is prepared (see section “feature preparation”).

When the feature is prepared, the scrum master checks that DoR is satisfied and changes the state to “Active”. During the “Active” phase, all child user stories are being developed. When all user stories have been closed, the scrum master checks the DoD and if that is fulfilled, the state is set to “Resolved”. In the final step, the product owner closes the feature.

Figure 5. Feature states

New

Draft features are defined during the epic preparation. When the epic has been set to “Active”, the work to refine and implement the features is intensified.
There are different types of features related to architecture, development, enabler, UX, and test.
Features are refined continuously, the goal is to have work planned for one increment ahead.
Feature definition includes; solution design, acceptance criteria, draft user stories, an initial estimate, and initial iteration path and is controlled by the DoR.
Refinement meetings between product owner and teams shall be organized (e.g. weekly) to secure successful transfer from epic to feature.
The feature shall be implemented in one increment. Split the feature if it is too large or if there exist appropriate smaller slices of functionality. The split shall make sense, avoiding the solution of “Part 1 and Part 2”.

Template for feature description

Feature template is not the same for the different streams – please use the guide as it makes sense to your context.

The following fields are mandatory:

The Title is a short phrase giving a name and the context.
The Description shall contain a benefit hypothesis, and proposed measurable benefit to the end-user or business. To clarify the description should contain details of the feature. To make the scope clear, clarify by defining what is NOT included.

If you want to have a more elaborate feature description there is an example in the appendix. If you have dependencies to other features that can’t be linked using the normal links (e.g. different template) it is also recommended to include manual links.

Figure 6. Feature description

Hint! The feature description template can be defined in the feature work item if choosing “Actions/Templates/New feature with description and acceptance criteria”.

Use the field acceptance criteria with statements like

It shall be possible to <criteria 1>
It shall be possible to <criteria 2>

Path

Area path in which release will the feature be delivered (copy from the epic).
Iteration path in which increment and sprint will the feature be done (sprint part should be added at program increment planning at the latest)

Effort estimate

The estimation shall cover all work related to the feature (e.g. design, development, test, and documentation). Estimation is done in two steps:

Initial feature estimate is set on draft feature when epic – “agreed”. This estimate is high level and is either done by points or expected effort (But ADO requires hours to be filled in) - Each release needs to set a common approach.
Refined estimate when the feature is “ready”. This new estimate should be based on the draft user story estimates.

Remember that even if you use points when doing estimates for features, they must be translated to hours when entered into ADO.

Below is an example of a table comparing the alternatives:

Points	Hours	Man weeks	Comment - Example of what it could be in reality
1	60	2	e.g. 1 team member for 2 weeks
2	120	4	e.g. 1 team member for 4 weeks
3	180	6	e.g. 1 team member for half increment (~6,5 weeks)
5	300	10	e.g. 1 team member for most of increment (~13 weeks)
8	480	16	e.g. 2-3 team members for half increment (~6,5 weeks)
13	780	26	e.g. 2 team members for full increment (~13 weeks)

Classification

Value area:

Architectural= Architecture work (an enabler related to architecture)
Business = Implementing a system requirement (used for development, UX, and test features).
Enabler = Solving an enabling technical matter (refactor, upgrade, etc.).

Security-relevant Consider if it is likely that work will affect a security-critical component, as listed (already or to be) in the security criticality analysis, modify a component’s attack surface, or is the work in some other way security-relevant (this may motivate a revised criticality analysis). Some examples are modifications in functionality for authentication, access control, integrity checking, encryption, or protection measures for DoS attacks.

Details about security criticality analysis can be found in the Security Criticality Analysis guide.

True = Feature is security-relevant
False = Feature is NOT security-relevant

If a feature is defined as security-relevant a security-relevant argument must be filled out (in the dedicated field).

E.g.

“The feature involves updating component xxx which has been defined as security critical”.
“The feature scope includes remote access/back up/input validation/…”.

Related work

Make links to epic (parent).
Make links to user stories (child).
It is also recommended to make links to related features/epics (e.g. dependencies).

All features shall be linked to an epic, for new enabler features a new epic might be needed.

In addition, some fields will not be mandatory, e.g. priority, risk, business value, time criticality, and start/target date.

DoR for a feature

Before work on a feature is started the following must be considered:

Understandable Title and Description
Testable acceptance criteria established
If/how to demo defined
The feature is estimated to ensure it can be completed in an increment
Preliminary design ready
Draft user stories
Link to Epic
Dependencies on other features defined
The area and iteration path is set
Security impact considered
The feature is ranked in the backlog

The feature is set to active in ADO by the team and “Iteration Path” is set. Note that for features, a review of a feature is optional (as opposed to epics).

Active

Implementation of features

Features are refined into user stories and implemented in the sprints.
Follow up on progress – remove impediments.

If the feature needs to be paused (e.g. due to changed product manager priorities, delayed delivery of dependent functionality, or unveiled technical uncertainties) the epic shall be:

Set the feature to “New” with the reason “Implementation halted”.
Update iteration path to agreed new iteration or without defined iteration if it is not yet set.
In the discussion field elaborate on the reason to pause, and describe how far the work has proceeded.
Ensure that linked child work items, not yet closed, have been managed in the same way.
Ensure that dependent features are informed.

Test of features

Test cases to verify the feature shall be developed in parallel with the implementation of user stories. Input to the test cases is the feature acceptance criteria. These tests are automated and include relevant hardware to secure. To be able to follow up on the feature test activities a user story under the feature should be created.

When all work has finished with a feature and all underlying user stories (development and test) are set to “Closed”, the features are set to “Resolved”.

Resolved

DoD for a feature

Before a feature can be set to state “Closed” the following DoD must be checked:

All child stories are closed
All unit and component tests passed
Component documentation approved
Demo performed (or planned)

The scrum master reviews the DoD, sets the feature to “Closed”, and informs key stakeholders (e.g. product owner, architect, release owner, configuration manager, quality control manager, and test lead).

Closed

After closure, the feature will not be maintained.

The flow of epics and features

Previous chapters have explained how one epic/feature is managed – this chapter describes how epics/features are handled as a group both from release and increment perspective and also how epics and features relate to each other.

Epic flow

The epic flow in a release is described below:

Figure X. Epic flow

Feature flow

The Feature flow in a release is described below:

Figure X. Feature flow

Changes to requirements

System epics

System epics = system requirements (SR).
Before G1, the product manager changes the SRs continuously.
Between G1-G2, the product manager changes the SRs with close communication with the product owner.
After G2 (SR approval), then change requests handling on SRs in CCB. (for details see PM process [1])

Epic

Before DoR, the product owner (business) / architect (enabler) continuously updates the epics. If changes to epics are identified that significantly differ compared to G/MS 2 assumption, it must be coordinated between the product manager and product owner, and if not possible to resolve escalated to release owner / SteCo.
Between DoR and DoD, changes to epics shall be discussed and agreed upon with the product owner and development team (the product manager should be considered). If changes to epics are identified that significantly differ compared to G/MS 2 assumption, it must be coordinated between the product manager and product owner, and if not possible to resolve escalated to release owner / SteCo. The conclusion shall be documented in the epic discussion field, including what was agreed upon, and who was involved.
After DoD, then no change, instead, create a new epic.

Feature

Before DoR, the Team and PO continuously update the features.
Between DoR and DoD, changes to features shall be discussed and agreed upon with the product owner and development team. The conclusion shall be documented in the feature discussion field, including what was agreed upon, and who was involved.
After DoD, no change, instead, create a new feature.

User story

Before DoR the team continuously updates the user stories.
Between DoR and DoD the changes are approved by the product owner (often delegated to the scrum master).
After DoD, no change, instead, create a new user story.

References

[1] 3BSE055359, Managing Market Requirements, and System Requirements

Appendix

Epic and feature refined descriptions

Below follows an example of how epics and feature descriptions can be further refined:

Epic

Customer info

Example: Tenet, Norwegian government electrical company PAEN Dolwin 5 ABB project ABB responsible contact: Kai Hanssen Problem Statement: What is the problem this epic solves? From the user/customer perspective? From ABB’s perspective?

Benefit statement

Why is this epic important from the customer’s perspective? What will be the main new benefit for the customer?
A statement describing which problem it is going to solve.
Tech/architectural changes - what is the benefit for the customer?

Business value

What will ABB as a company benefit from this? New market opportunities? Cost savings?
The context in the bigger picture/overall vision.
Tech/architectural changes - what is the value for the business?

Assumptions and dependencies

Any technical and customer dependencies?
Internal dependencies?
The motivation of this epic or the dependency it is driving.

Target personas/users

Example: Börje - Edge Administrator Birgitta - L3 support

Deliverables

List of deliverables from the perspective of the customer and/or R&D.
Info on how this would provide the requested functionality in the end.
How to provide better guidance? Must be agreed with customers.

Impact analysis

Mention any impact on current existing functionality.

Nonfunctional requirements

Corporate Social Responsibility.
Comments and considerations from R&D and customer perspective.
UX.
Comments and considerations from R&D and customer perspective.

Documentation

Comments and considerations from R&D and customer perspective.

OSS

Comments and considerations.

Feature

Problem statement (What is the problem we are trying to resolve?)

What is the problem we are trying to solve?
The expectation of the resulting solution.
Description of the problem.

Benefit statement (Why do we want this feature? What is the value added by the feature?)

Why do we want to implement this feature, and what is the value added by doing this?
Impact analysis.
Where
- Where is this needed, in which project or product?
- Customer/project of ABB. e.g. Dolwin.

Requirement owner (Who wants this feature?)

Who wants this?
Who is the stakeholder?
Source of information.

Target user (Who will use this feature?)

Who will use this feature (Personas)?

Target deliverables (What are the deliverables? Are there any hard deadlines connected with the deliverables?)

When is this needed?
Are there multiple deliveries expected?

Solution proposal (How are the requirements supposed to be implemented Link to the wiki?)

How requirements are supposed to be implemented?
Link to wiki.
Design idea.
Implementation design.

Architectural considerations (Optional)

What part of the system is involved?
Risks.
Dependencies.
What is in scope?
What is out of scope?

Front end (Optional)

Style guide alignment.
UX approval on the implemented feature.
UX concept/prototype.
Personas.
User research.

How-to Work with System Architecture Epics and Features

Mon, 01 Jan 0001 00:00:00 +0000

The purpose of this guide is to provide hands-on support to the roles involved in defining the system architecture influenced by requirements, in PCP R&D QMS captured in the system epics, epics, and features.

As background to this guide, there is an existing conceptual REQ guide that focuses on the big picture.

The System architecture is strongly influenced by Technology and System Requirements. The overall architecture work is broken down into System Epics, Epics, and Features.

Architectural activities are one type of enabler from the perspective of SAFe methodology. However, to distinguish the architectural activities, this work is identified in ADO as the architectural value area.

Intended for

Architects
Product owners
Developers
Testers

In addition other roles with interest in the architectural work breakdown like Release owner, Product manager, and Supporting processes.

Overview

Work item hierarchy as below (every work item can have many children but only one parent). Each work item has Architecture as Value Area to differentiate it from the Technology and System Requirements work items.

System Epic
- Epic
  - Feature

The architectural System Epic is sliced differently, covering multiple Technology and System Requirements.

Architectural System Epic

System and technology requirements are defined in Decision Focus (DF) for release planning. An Architectural System Epic covers one or several requirements, grouping the requirement into an architectural topic. In the process of defining the system architecture, the system architects create the system architecture epics based on the technology requirements.

The relationship between technology or system requirements and an Architectural System Epic is captured in the SR ID field for the Architectural System Epic.

A System Epic life cycle duration covers multiple increments. It’s active for as long as there are children associated with it, after that point the system epic is closed. If new work within this topic is needed, the system epic is reopened.

The area path assigned to System Architecture and Value Area is set to Architectural.

System Epics vs. Requirements

Although requirements (System, Product, or Technology) are typically Product Managers’ tools to provide functional and non-functional requirements to R&D, also R&D is entitled to file requirements.

This is typically done by Architects pushing for non-functional requirements related to architecture, design, and technology. Architects push for such requirements via the R&D toolchain by filing System Epics that will be translated into Epics.

The System Epics created by Architects (that will eventually translate into Epics/Features/User Stories/Tasks) may have higher or lower priority than a functional requirement created by PMs. This depends on a case by case, but it is important to notice that these epics value as much as the ones created by Product Management Team.

As happens for functional requirements, also the architectural requirements need to be discussed in regular epic grooming sessions and planned, according to the priority given by the originator, to the proper PI.

if the requirement is created by Architecture team it may not necessarily have a related SR/TR in DFN to be linked

Architectural Epic

Architectural Epics are defined as a breakdown of the Architectural System Epics, one or several Architectural Epic are strictly associated with one Architectural System Epic as a parent/child relationship.

Each Architectural Epic always has one Definition of Ready and one Definition of Done, for more details refer to the Definition of Ready and Definition of Done Guideline. Templates are available in AppGami for Architectural Epic.

The Architectural Epic can focus either on investigation or documentation. Typically an architectural epic produces architectural documentation which would include some investigation. For some more details, an investigation is required, and this can be tracked with an investigation of an architectural epic. Depending on the focus, different DoDs are used.

An architectural epic can span 2 or more increments and is closed when the Definition of Done is fulfilled.

The area path assigned to System Architecture and Value Area is set to Architectural.

Architectural Epic Overview / Life Cycle

Work Item State	Details
New	Work on the activity has not started.
Active	Architecture activities has started. Definition of Ready conditions have been met.
Resolved	The core activities are completed, but the work is not concluded.
Closed	All activities have concluded; Definition of Done conditions have been met.
Removed	The work item is no longer applicable, e.g. based on an assessment of need or a change in scope.

Architectural Feature

Architectural Features are a further breakdown of the architectural epic into more details than expressed in the epic. Feature work items can be used to describe activities related to creating documentation for an architecture feature; for reviewing documents (e.g. for tracking PM-Architect agreement discussions), or for investigations or other objectives. In ADO, the Feature work item:

Is typically scoped for completion within the increment
Is assigned to a target sprint using the Iteration path field
Is committed to a PCP System Planning Iteration

Each Architectural Feature always has one Definition of Ready and one Definition of Done, for more details refer to the Definition of Ready and Definition of Done Guideline. Templates are available in AppGami for Architectural Features.

Architecture documents are output from the Architectural Features and are published to the main branch of the wiki. Documents have four phases of readiness:

Status	Description
draft	An architect has published document prior to peer review
in-review	Architecture team is conducting a peer review
pending	Document is ready for review by a broader audience (PCP R&D and PMs)
accepted	Reviews are completed by architecture and PMs: the accepted architecture is as documented

The Architectural Feature is closed when the DoD conditions are met.

The area path assigned to System Architecture and Value Area is set to Architectural.

Architectural Feature Overview / Life Cycle

Work Item State	Details	Documentation Feature Work Item
New	Work on the activity has not started.	The work item may be for creating a new document or revising an existing one.
Active	Architecture activities has started. Definition of Ready conditions have been met.	Any interim version of the architecture document would have draft status. The document may be published as a draft, or may be in a working branch as draft. If there is an original document it may already be published in some other state.
Resolved	The core activities are completed, but the work is not concluded.	The document is in review by the architecture team: a pull request is in review.
Closed	All activities have concluded; Definition of Done conditions have been met.	The document has been reviewed by the architecture team and the document has been published (merged to the main branch) with pending status
Removed	The work item is no longer applicable, e.g. based on an assessment of need or a change in scope.	–

Kanban

Mon, 01 Jan 0001 00:00:00 +0000

Kanban is a Japanese term meaning signboard or billboard. An industrial engineer named Taiichi Ohno is credited with having developed Kanban at Toyota Motor Corporation to improve manufacturing efficiency

Kanban for software development teams

While Kanban was created to help with manufacturing, software development teams share many of the same goals, including wanting to increase their flow and throughput. Using some of the guiding principles of Kanban listed below, teams can often improve their efficiency and deliver value to their users faster.

In this article, we’ll focus on Kanban as it applies to software development teams.

Key Kanban principles

Pull-model

Software development teams historically have had work pushed on them as stakeholders request more functionality. This is often accompanied by tight deadlines. A common side effect of this behavior is that quality suffers as the team is forced to take shortcuts necessary to deliver the functionality within the timeframe.

Kanban helps a team focus on maintaining an agreed-upon level of quality that must be met before the team can claim a piece of work as done. Stakeholders add requests to a backlog, and then the team “pulls” work into their workflow as capacity becomes available.

Visualize work

Understanding the status of a software development team in terms of both process and progress can be challenging. People can more easily understand the current state of work if it is shown using a visual representation rather than a large list of work items or a document describing the work being done.

Visualization of work is a key Kanban principle. Kanban addresses this visualization using Kanban boards (discussed in more detail later in this article). Visualizing the work to be done as cards on a board, in different states, allows you to easily see the “big picture” of where the project currently stands, as well as identify potential bottlenecks that could affect productivity.

Limit work in progress

Teams that try to work on too many things often suffer from reduced productivity due to frequent and costly context-switching. The team is busy, but work just doesn’t seem to be getting done, resulting in unacceptably high lead times. To address this, limiting the number of backlog items a team is working on at any given time helps increase focus while reducing context switching.

The maximum number of items a team decides to work on at any point in time is known as the WIP limit. A well-disciplined team will work to ensure they are not exceeding their WIP limit. Should this occur, the team will investigate the reason and work to solve the root cause of the issue.

Continuous improvement

For software development teams to continuously improve, they need ways to measure their team’s effectiveness and throughput. Kanban, through the use of the Kanban board, provides a dynamic view of the state of work in a workflow. This allows the team to experiment with different processes and evaluate the impact on the flow of work more easily. Teams that practice Kanban often utilizes measurements such as lead times and cycle times and generally embrace the benefits offered for continuous improvement.

Kanban boards

A Kanban board is just one of many tools you can use to implement Kanban practices in a team. A Kanban board can be a physical board or a software application that shows cards arranged into columns. Typical column names may include To-do, Doing, and Done, but teams can customize this to suit the states in their workflow. For example; New, Development, Testing, UAT, and Done.

Software-based Kanban boards can display cards corresponding to Product Backlog Items and include links to things such as tasks and test cases. The following screenshot shows an example of a software-based Kanban board.

On a Kanban board, a WIP limit is applied to all “in-progress” columns. The first and last columns on a Kanban board do not have WIP limits. In Figure 3, assuming the WIP limit is 5, the testing column is exceeding the limit as illustrated by the bold column title and the change in color to red. This indicates that there may be a bottleneck in testing that is impeding the team’s flow. Once identified, the team can determine an appropriate course of action to remove the bottleneck.

Cumulative flow diagrams

A common addition to software-based Kanban boards is a chart called a Cumulative Flow Diagram (CFD). This chart illustrates the number of items in each state over time, typically multiple months. The horizontal axis shows the timeline, while the vertical axis shows the number of Product Backlog Items. Colors are used to indicate the state (or column) the cards are currently in.

This chart is particularly useful for identifying trends over time, including bottlenecks and other disruptions to a team’s velocity. An example of a good CFD would show a consistent upward trend while the team is working on the project. The various “stripes” across the top of the chart area should be roughly parallel if the team is working within their WIP limits.

IF one or more of the stripes show a bulge, this is usually a clear indicator of a bottleneck or impediment in the team’s flow. In the CFD shown below, you can see the completed work (green) is flat, while the previous state, Testing, is growing, which indicates a probable bottleneck.

Agile, Scrum, and Kanban

While broadly fitting under the umbrella of Agile, both Scrum and Kanban are quite different. A few of the most notable differentiators include; scrum focuses on fixed-length sprints where Kanban is more of a continuous flow model; Scrum has defined roles where Kanban does not define any specific roles for the team, and Scrum uses velocity as a key metric whereas Kanban champions the use of cycle time.

In calling out the differences in the previous paragraph, it is also common for teams to adopt aspects of both Scrum and Kanban to help them work most effectively. Remember, regardless of which characteristics you choose, you can always review and adapt until you get the best fit for your team. Start simple and don’t lose sight of the most important thing – delivering value regularly to your users!

Klocwork

Mon, 01 Jan 0001 00:00:00 +0000

Klocwork static code analysis tool identifies software security, safety, quality, and reliability issues helping to enforce compliance with standards. The tool has many rules to choose from.

This is one of the ABB global SCA tools, and the only one approved for safety.

Where to find the tool

Klocwork can be found here: https://www.perforce.com/products/klocwork

It can be used locally and on a build server. There are Klocwork Desktop plug-ins available, e.g. for Visual Studio and Eclipse.

Description

Klocwork static code analysis tool supports C, C++, C#, Java, and JavaScript. The tool has many rules and collections of rules to choose from. The used ruleset is overlapping with other tools but forms a base and leverages what the tool is capable of.

Motivation

Klocwork identifies critical security and safety vulnerabilities and quality defects and helps developers create more maintainable code.

How to analyze the code

Desktop plugin analysis

C/C++ code: By default, the Klocwork Visual Studio extension runs whenever you save a file. If you prefer, you can use on-the-fly analysis instead so that Klocwork detects issues when you open files and as you type.

C# code: For pure C# or mixed C/C++ and C# solutions, right-click the solution and select Analyze Solution. Or right-click a project and select Analyze Selection. A full solution or project analysis detects both C/C++ and C# issues.

When Klocwork detects issues in a file, you see issue markers on the left and right margins of the editor. The left markers (chevrons) scroll with the text. When Klocwork detects more than one issue on the same line, the left gutter markers display only the highest-priority issue.

Server analysis

An analysis shall be run on the server as part of a pull request or before integrating the code. A full analysis shall be performed regularly, for instance, every night. The issues are listed on the Klocwork server per project.

New and changed code

New and changed code shall be analyzed during the code review, e.g. as part of a pull request.

Existing codebase

It is possible to baseline the existing issues in the codebase. Critical security errors and warnings shall be fixed, other issues are recommended to baseline.

New versions

Klocwork release schedule is one new version each quarter, hence version naming is year.quarter.

The release notes state which Visual Studio versions are supported. When using a newer version one can expect issues with the analysis of STL as Microsoft frequently changes its implementation.

Reevaluate all overrides, done in file overrides.h, to see if the analysis engine has improved. The Modern engine should hopefully be able to parse the code cleanly without workarounds.

Ruleset

Storage

The ruleset for a project is stored in one configuration file together with the code, e.g. in a git repo.

Version control

One configuration file analysis_profile.pconf for each project is placed and version-controlled together with the code.

Add/remove rules

Rules are modified, added, and removed by changing the analysis_profile.pconf file.

New rule set from new tool version

When a new version of the tool has been provided, a tool responsible needs to read the release notes for the new version and consider if new rules should be used in the ruleset. By default, the new rules are normally enabled, which can cause a lot of new issues in the Klocwork analysis. The configuration file should be updated to reflect this.

Standards

Klocwork has checkers for the CWE Top 25 most dangerous software weaknesses, which complies with the standard IEC 62443-4-1.

Monitoring

Monitoring is done on the Klocwork server, where different views can be set up to view different issues, statuses, severities, etc. Issues can be filtered in many ways.

A pull-request in Azure DevOps shall be set up with a required check that blocks the pull request from completing while there are unhandled new Klocwork issues in the code.

Deviation reports can be produced from Klocwork.

Severity levels

An issue severity is made up of a level from 1 through 10, plus a label such as Warning. Each checker has a default severity. By default, checkers are assigned severities 1 through 4. Custom checkers are assigned severity 4 by default. The available severity levels and their default labels are as follows: 1 - Critical 2 - Error 3 - Warning 4 - Review 5 - Severity 5 6 - Severity 6 7 - Severity 7 8 - Severity 8 9 - Severity 9 10 - Severity 10

How to handle deviations

Newfound issues that require some sort of deviation shall be commented in the ongoing pull request and resolved by a reviewer:

Klocwork pipeline finds an issue. The issue ID shall be documented in a comment in the pull request on the failing source code row.
Handle issue in Klocwork by setting the correct status and in the motivating comment refer to the pull request id. Possible statuses:
- Not a problem: Used for false positives.
- Ignore: suppress issue that can’t be fixed in code, or usage of 3rd Party API, etc.
- Defer: avoid using it, but present due to legacy issues.
Pull request reviewer (preferable the team member being familiar with the code) resolves the comment if motivation in Klocwork is sufficient. The reviewer also adds a “Reviewed by N N” statement to the Klocwork comment.

ABB Klocwork security compliance

The ABB taxonomy ‘ABB minimum security checks’ in Klocwork can be used to fulfill the ABB Minimum Cyber Security Requirements in Klocwork.

Klocwork has checkers for the CWE Top 25 most dangerous software weaknesses.

List of Document Templates

Mon, 01 Jan 0001 00:00:00 +0000

PCP R&D document templates Approved templates in Templafy Recommended markdown templates Brownfield legacy templates Process Teams

Approved templates are available in Templafy

Please first consider using the recommended markdown templates for the ADO Wiki.

Please use the legacy templates only when updating already released systems and products or for new safety development ( brownfield).

Talk to the Process Teams for further recommendations.

Requirements

Id	Name	Comment
3BSE001280_en	Requirement specification.docx	Template for requirements. Should be avoided, since requirements are managed in DFN and ADO
3BSE080616_en	Requirement Specification (TFS and Scribe).docx	Template used when generating requirements from TFS in Control.
3BSE025506_en	Implementation Proposal.docx	Implementation Proposal (IMP) for analyzing requirements (dev. stream) and propose a solution
3BSE039052_en	Implementation Proposal System.docx	Implementation Proposal (IMP) for analyzing system requirements (system stream) and propose solution
3BSE039362_en	Implementation Proposal Estimation.xlsx	Implementation Proposal (IMP) Estimation

▶️ Requirement templates in Templafy:

Word Templates Excel Templates

Architecture

Id	Name	Comment
3BSE062407_en	Architecture Description (EA and Scribe).docx	Generated from Enterprise Architect (EA). Used for system and product architecture in Control.

▶️ Architecture templates in Templafy:

Word Templates

Hardware Development

Id	Name	Comment
3BSE044948_en	Description of Function HW.docx	HW function. Ref to requirements, application, features, block diagram, etc.
3BSE093821_en	Design Description HW.docx	HW design. SIL, explosion protection, electrical safety. PCBs
3BSE042061_en	Environmental Type Test Description.docx	Describes environmental tests, like climate endurance, mechanical endurance, corrosive gas, etc.
3BSE044172_en	Environmental Type Test Record.docx	Record of the result of environmental tests
3BSE084851_en	EMS Checklist.xlsx	EMS = Electronic Manufacturing Services
7PAA008756_en	Samples approval checklist	For Mechanical samples
7PAA006927_en	Engineering Service Request	For requests by engineering services, primarily GPV
7PAA012480_en	RCA Report template(Lifecycle Parts Services offering)	Inspection and test report

▶️ Hardware Development templates in Templafy:

Word Templates Excel Templates

Specific templates for Explosion protection development

Id	Name	Comment
7PAA000912_en	Ex Component List.xslx	Used by Ex team for Certification purposes
7PAA007159_en	Ex Application Report Template.docx	Used by Ex team for certification
7PAA007991_en	Ex type test record template.docx	Used by Ex team for certification

▶️ Explosion Protection templates in Templafy:

Word Templates Excel Templates

Software Development

Id	Name	Comment
3BSE040221_en	Description of Function.docx	Describes function and design. References back to requirements. Covers performance, limitations, security, safety aspects, etc. Not recommended for new development.
3BSE041242_en	Description of Function XYZLib.docx	Describe control libraries, similar to DoF
3BSE056640_en	Description of Function SW (EA and Scribe).docx	Template used when generating information from EA
3BSE040497_en	Design Description.docx	Design of systems and subsystems. Interfaces and class diagrams.
3BSE056642_en	Design Description SW (EA and Scribe).docx	Generated from Enterprise Architect (EA), used by Control
3BSE056641_en	Interface Description SW (EA and Scribe)	-
3BSE037724_en	Design_Module Test Description and Record.docx	-
3BSE041149_en	Function or Component Type Test Record.docx	-
3BSE041148_en	Function_Component Type Test Description.docx	Description of functional type tests of a component
3BSE037719_en	Function_Component Type Test Description and Record.docx	Functional test and record of a component.
3BSE024269_en	Code Review Record.docx	-

▶️ Software Development templates in Templafy:

Word Templates

Test

Id	Name	Comment
7PAA015399_en	Test Strategy and Plan.docx	Describes the test strategy, plan, structure, environments, etc.
3BSE034593_en	Product Type Test Description.docx	All test cases in ADO. Not recommended for new development.
3BSE043864_en	Product Type Test Record.docx	Product type test record. The test result is captured in ADO. Not recommended for new development.
3BSE010767_en	Type Test Plan.docx	Type test plan contains information about test strategy, structure, etc. (not to be confused with ADO Test Plan). Not recommended for new development.
3BSE045565_en	Test Summary and Final Conclusion of Test.xlsx	A summary of all tests performed on all test levels - ST, LLIT, FTT, ETT, PTT, SVT, SRT, STT.
3BSE061530_en	Checklist for Beta, IVA and Start of Type Test.xslx	Checklist for Beta and Start of PTT/STT/RAT/IVA/SVT
3BSE086887_en	PTTD Safety Requirement Validation (TFS and Scribe).docx	-

▶️ Test templates in Templafy:

Word Templates Excel Templates

Release

Id	Name	Comment
3BSE039313_en	Names on RACI.xlsx	Assigns people to roles involved in review/approval of documents

▶️ Release templates in Templafy:

Excel Templates

L4 & Maintenance

Id	Name	Comment
7PAA001404_en	TC and Rollup Release Notes.docx	-
3BSE045796_en	Customer Authorization Temporary Correction non-Safety.docx	-
3BSE046924_en	Checklist for temporary correction.xlsm	Checklist for TCs and interference free TCs

▶️ L4 & Maintenance templates in Templafy:

Word Templates Excel Templates

Additional Templates

The Field Communication templates are owned by Product and Portfolio Management (PPM) and used by “L4 & Maintenance”.

Id	Name	Comment
3BSE037120	Safety Report.docx	Select a template depending on the DMS you use
3BSE037123	Technical Description.docx	-
3BSE071315	Cyber Security Advisory.docx	-
2PAA124139	Cyber Security Notification.docx	-
2PAA123022	Product Bulletin Internal.docx	-
2PAA123021	Technical Description Internal.docx	-
3BSE052609	Product Alert.docx	-
3BSE037122	Product Bulletin.docx	-

▶️L4 & Maintenance additional templates:

Word Templates

Configuration Management

Id	Name	Comment
7PAA001177F	Configuration Management Plan.docx	PCP level Configuration Management Plan template
7PAA004621F	Safety Tool Selection Report.docx	Tool evaluation for approval by Safety
3BSE042287	HW Version Log.docx	-
3BSE001281	Version Specification.docx	-
3BSE039765	Baseline Plan.docx	-
3BSE054357	Version List.docx	-
3BSE041627	Configuration Management Compliance Plan.docx	-
3BSE052347	Release Preparations.docx	-
3BSE044689	Archiving Record.docx	-
3BSE054110	PCA Checklist and Report.docx	Not recommended for new development. See How-to Perform Configuration Audits.
3BSE054108	FCA Checklist and Report.docx	Not recommended for new development. See How-to Perform Configuration Audits.
3BSE057007	Approved SW and HW Versions for Test.xlsx	-

▶️ Configuration Management templates in Templafy:

Word Templates Excel Templates

3rd-party and OSS

Placeholder for 3rd-party and OSS templates. Most information is captured in ADO and DFN (no templates needed)

Quality & KPIs

Id	Name	Comment
7PAA003088_en	Quality Plan.docx	Quality Plan with release goals, KPIs, process deviations, etc.
7PAA003087_en	Quality Report.pptx	Quality Report for milestones and gates

▶️ Quality & KPIs templates in Templafy:

Word Templates PowerPoint Templates

Intellectual Property

Id	Name	Comment
2PAA121471_en	IP Risk Register.xlsm	Intellectual Property Risks
2PAA121473_en	IP Strategy.docx	Intellectual Property Strategy

▶️ Intellectual Property templates in Templafy:

Word Templates Excel Templates

Cyber Security

Id	Name	Comment
7PAA013087	PAPCP Product Security Assessment Tool	PAPCP tool based on 9AKK108467A3796 Product Security Standard - Assessment Tool Rev A
7PAA013086	PAPCP Security Development Life Cycle Assessment Tool	PAPCP tool based on 9AKK108467A3794 Security Development Life Cycle Standard - Assessment Tool Rev A
7PAA013273	PAPCP Cloud Security Assessment Tool	PAPCP tool based on 9AKK108467A3795 Cloud Security Assessment Tool Rev A
7PAA014751	PAPCP Light Weight Assessment Checklist	PAPCP Assessment Checklist based on 7PAA013086 PAPCP Security Development Life Cycle Assessment Tool and PAPCP Product Security Assessment Tool

▶️ Cyber Security templates in Templafy:

Excel Templates

Functional Safety

Id	Name	Comment
3BSE087886_en	Impact Analysis Report (TFS and Scribe).docx	-

▶️Functional Safety templates:

Brownfield templates and documentation

Integrated Project Management

Id	Name	Comment
3BSE034121_en	Project Description and Plan.docx	Description of the project (release)
3BSE015958_en	Final Project Report.docx	Final project report before project is closed
3BSE055542_en	System Integration Plan.docx	System integration plan with integration points
7PAA007509_en	Document Control Plan.xslx	Document Control Plan (DCP) lists all documents for the project (release) and status
3BSE034486_en	Action (ADI) list.xlsx	Action/Decision/Information (ADI) list used to capture minutes from SteCo meetings
3BSE040876_en	Rollup Checklist.xlsx	Checklist for rollups, certified correction and small projects (releases)

▶️Integrated Project Management templates in Templafy:

Word Templates Excel Templates

Additional Templates

Templates used but not owned by R&D

Id	Name	Comment
2PAA121451	R&D and Technology - R&D and Technology - Project Execution Deliverables and Milestone Tracker.xlsm	Milestone tracker for R&D, managed by PMO
2PAA121438	Project Status Update - SteCo Meeting.pptx	SteCo meeting template, managed by PMO. It contains IPM schedule, risks overview, ADI, etc.
2PAA121462	Risk Register.xlsx	Risk Register to capture and monitor risks (can be generated from ADO)
2PAA121452	PPM and Divisions Project Execution Deliverables and Milestone Tracker.xlsm	Used for System releases, managed by PMO
2PAA121454	Business Processes & IS - Project Execution Deliverables and Milestone Tracker.xlsm	Used for System releases, managed by PMO
2PAA121453	L3 Project Execution Deliverables and Milestone Tracker.xlsm	Used for System releases, managed by PMO
2PAA121456	P&F Project Execution Deliverables and Milestone Tracker.xlsm	Used for System releases, managed by PMO
2PAA121455	P&L Project Execution Deliverables and Milestone Tracker.xlsm	Used for System releases, managed by PMO
2PAA121457	IE Project Execution Deliverables and Milestone Tracker.xlsm	Used for System releases, managed by PMO
2PAA121458	SQM Project Execution Deliverables and Milestone Tracker.xlsm	Used for System releases, managed by PMO
7PAA008779	PA PCP Gate Model Checklist.xlsx	Used for System release, managed by PMO
7PAA015786	PPM-SE Project Execution Deliverables and Milestone Tracker.xlsm	Sales Enablement, managed by PMO
7PAA015789	Checklist for Yearly and Frequent Release.xlsm	Used for frequent/yearly release, managed by PMO
7PAA016242	Lesson Learned.xlsx	Used for lesson learned, managed by PMO

▶️IPM additional templates:

Excel Templates

Document Management

Id	Name	Comment
2PAA104551_en	Review record.xlsm	Review record to capture comments in document reviews
3BSE028024_en	Checklist for Reviews	Checklist for formal review

▶️Document Management Templates in Templafy:

Excel Templates Word Templates

Sources

Templafy - PCP Templates DMS - Safety/Brownfield Templates SharePoint Template Area Field Communication Template Area

Document number generator:

IDG - Generate number on 7PAANNNNNN

List of Markdown Templates

Mon, 01 Jan 0001 00:00:00 +0000

List of PCP R&D markdown templates recommended for streams and teams.

Talk to the Process Teams for further recommendations.

Requirements

None

Architecture

Name	Description
Architecture Review Checklist	Architecture review checklist for pull requests in Markdown.
Product Capability Template	Product capability markdown template for ADO.

Software Development

Name	Description
Component Capability Template	Component capability markdown template.
Component Dynamic Behavior Template	Dynamic behavior template for components.
Describe the Usage of SCA Tool Template	When a new static code analysis (SCA) tool has been chosen for a product or part of a product, it needs to be described to facilitate its use in the considered and other products.

The purpose of testing against performance requirements is to design test cases that demonstrate whether the requirements are fulfilled or not. Examples of performance requirements are:

A download to the controller with a small project should not take more than x minutes in 95% of the cases
In a standard workload, CPU usage should be less than 50%
OLU for a normal-size project should not take more than x minutes (excluding user communication) in 95% of the cases

The purpose of stress testing is to break the system, i.e. find circumstances under which the system will crash. During the process of determining the limits of the system, testing provides evidence that the system will work under normal conditions. Stress testing reveals faults like, for example, waste memory space, errors in timing sequence, and deadlocks. It is preferable to use a tool when stress testing. A load generator can simulate many users of the system, many processes, much data input to the system, and so forth.

Response timings are how long it takes for the system to respond to a request for a piece of information. The request could be initiated by a user, another system, or another process. Memory constraints are a definition of how large memory is allowed to be used. The testing of response timings and memory constraints should be done for average as well as worst-case conditions. Examples of response timings are:

The time to download a project to the controller
The time to open a new project
The time it takes the SM to answer a specific request from the PM

Product Capabilities

Mon, 01 Jan 0001 00:00:00 +0000

Product capabilities describe what the product “can do” for anyone who wants to understand its capabilities. They represent the product’s property and are updated throughout its lifecycle through multiple releases.

This guide describes the most basic parts of product capabilities. Specific add-ons, such as those to ensure Safety compliance, may be needed in the future.

Intended for

Product owners, test leads, architects, and product managers.

Purpose

Why do we write product capabilities?

Product capabilities documents serve as one consolidated place to describe high-level product capabilities. Without product capabilities, this kind of documentation would be scattered in epics, features, and the component’s capabilities. It would be difficult to get an overview of the product’s capabilities, and existing documentation would be too low-level.
Product capabilities are foremost intended for product managers, owners, and architects to understand whether the product meets expectations and for developers, testers, and new employees to get an overview of the current state of the product. Product capabilities also provide traceability to product tests. By reading product capabilities, the reader is informed about what has currently passed product tests. The test cases can also be analyzed in the associated product test suite.

Definition and clarifications

“What” and not “How”

Product capabilities shall describe what the product “can do” for anyone who wants to understand what the product is capable of.

The capabilities shall be described in a short format focusing on the “what” (without detailing internal interfaces/functionality that are not important to know about when using the product), while the “how” is defined in architecture and detailed design documentation. A bullet list is a common format in a product capabilities file since it usually lists all supported functionality briefly and concisely.

End-user/customer perspective

Product capabilities are written from an end-user or customer perspective. This means that product capabilities state what the end user can do when using the product in its current state, or in other words, which capabilities are interesting for the end user to know about to exploit the product fully.

Functionality support is described at a very high abstraction level. For example, the control platform’s capability to receive and use configuration files sent from the engineering tool is not stated in a product capability (but rather in the component capabilities). That would be too much “under the hood.” Instead, the product capability would state that the product supports the control execution of logic using Structured Text since it is important for the end user to know when using the product.

The current state of implemented and verified functionality

Capabilities serve as internal (ABB) documentation of what a product can do in its current state.

Future functionalities should not be written in a product capability. Only verified functionality should be stated in a product capability. Hence, the product capability updates can only be merged when the functionality has been tested.

Before closing an epic, the newly implemented functionality shall be documented in the corresponding product capabilities.

Structure - what abstraction level defines a product?

A product is the abstraction level above components and should be aligned with what the architecture documentation defines as products. Therefore it is important to involve the architect When defining a new product in this context.

Traceability

The automated product test cases are in the same repository as the product capabilities. They shall use the same naming conventions to make it easy to understand what test cases have been executed to verify each capability. If manual tests have been executed, a link to the location of their descriptions shall be provided.

Product capabilities, architecture documentation, and detailed design documentation should follow the same naming convention to make the relationship between the content of the different artifacts easy to understand.

“Traceability by naming convention” means that if, for example, “AC800M Execution Service” is a defined product in the architecture documentation, the exact same name must be used throughout the rest of the documentation and product test framework.

While traceability by naming convention in product capabilities, detail design documentation, architecture documentation, and product tests is considered enough in the initial phase of PCP QMS, it will be investigated if the traceability should be strengthened with product IDs in the future.

A product capability should also provide a link (linking can be done in different ways depending on stream conventions) to the location of the architecture design and detailed design documentation to make it easy for readers to find if they are interested in further reading.

What is not a product capability

A product capability is not a direct translation of traditional product requirements. Although product capabilities often will be drafted in temporary branches in parallel with implementation, the final merge of a product capability update is done after the capability has been implemented and tested. As input to implementation, system epics, epics, and features will be used (these work items are replacing the previously used product requirements). See the workflow visualization below for a better understanding.
A product capability should not be confused with architecture or detailed design documentation. Product capabilities are written as an outcome of implemented and tested epics or bug corrections and these work items were in an earlier step potentially defined with architecture and detailed design documentation as input.
In general, unsupported functionality should not be mentioned in a product capability. However, exceptions can be made if they help the reader understand the product’s current state.
A product capability does not describe full system functions but is limited to the product’s contribution to those system functions.

Usage/Workflow

Input

Input to a product capability is an epic description and the epic acceptance criteria. Although epics should be sufficient input for writing product capabilities, sometimes component capabilities can be used as additional input when writing product capabilities (often, product capabilities refer to component capabilities for more details.)

Reviewers

The product capabilities are written in Markdown (.md) files in the same repository as the product test source code. When the product’s capability is updated, it should be merged with a pull request ¹ linked to the corresponding task for the update. Through the parent-child links, the task is traceable to the corresponding epic (via user stories and features).

The pull request including the product capabilities update should be reviewed by the product manager, product owner, and the product tester (product capabilities are often written in collaboration between the product owner and product tester). The architect and relevant scrum masters are informed as optional reviewers.

Consumers

Examples of consumers of a product capability are product managers, product owners, and architects who agree that the implementation meets expectations. Consumers can also be developers and new employees who understand the current state of implementation on a high level. Finally, testers (especially on the product test level) consume product capabilities to understand what high-level functionality has already been tested.

Product capabilities may also serve as input to end-user documentation.

Workflow/traceability diagram

As seen below, input to implementation and documentation starts with system epics, which are then refined into smaller, more detailed work packages. The information input to a product capability comes mainly from an epic since they have corresponding abstraction levels. However, there will be tasks (small work packages) to update the product capabilities and track the actual progress of the update.

Product Capability Template

Mon, 01 Jan 0001 00:00:00 +0000

Product capability markdown template for ADO.

Markdown template

Copy the contents to an empty markdown file and start editing. Remove the help text in block quotes and any unused sections.

# \<Product name\> capabilities (E.g. NC800M capabilities)

---

# Table of contents

[1. Overview](#Overview)
[2. Capabilities](#Chapter-2.-Capabilities)
etc.

## Chapter 1. Overview

Describe an overview of the product.
It might be a good idea to prepare a block diagram in plantUML if it supports the reader's understanding.

## Chapter 2. Capabilities

Here details about the supported capabilities can be given.
Include plantUML sequence diagrams if they will help the reader's understanding.

### Chapter 2.1 Subchapter (E.g. Connectivity capabilities)

### Chapter 2.2 Subchapter (E.g. Redundancy capabilities)

### Chapter 2.3 Subchapter (E.g. OS Support capabilities)

## Chapter 3. Product tests

The described capabilities above have been verified using automated tests located in the same repository as this document and using manual tests described in the Test Suite(?) found here: [Link]()

## Chapter 4. Related documentation

For a detailed design and architecture description of NC800M, follow these links:

- [Architecture of NC800M](https://dev.azure.com/ABB-PA-CommonComponents/IA_Common/_wiki/wikis/System%20Architecture?pagePath=/System%20Parts/NC800M)
- Detail design: NC800M Platform: file://abb-is-000633.nmea.abb.com/Successful_Builds/CCCP/continuous_integration/Platform/int/SDKs/LatestDocumentation/html/index.html
- Detail design: NC800M Execution service: file://abb-is-000633.nmea.abb.com/Successful_Builds/CCCP/continuous_integration/AC800MExecService/LatestDocumentation/html/index.html
...

Related components and links to their component capabilities documents:

| Components |
| :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: |
| [AC800M Execution Service](https://dev.azure.com/ABB-PA-CommonComponents/IA_Common/_git/Control_AC800MExecService?path=/AC800MExecService/documentation/AC800M/Capabilities.md&_a=preview) |
| [Component X](https://google.com) |


## Chapter 5. Definitions/terminology

| Term | Definition |
| :---: | :-------------------- |
| ARM | Advanced RISC Machine |

---

## Chapter 6. References

| Ref | Document Identity | Document Title |
| :---: | :----------------------------------------------------------------: | :------------------------ |
| [ReX] | [Document ID](https://google.com) | Threat model for NC800M |
| [ReY] | [PlantUML Sequence Diagram](https://plantuml.com/sequence-diagram) | PlantUML Sequence Diagram |

R&D KPIs

Mon, 01 Jan 0001 00:00:00 +0000

Key performance indicators (KPIs) are used within ELSP R&D to better understand, control, and manage the organization.

This guide describes the principles of KPIs, the standard KPIs for R&D releases, and the roles and responsibilities involved in KPIs.

Intended for

Quality control managers (QCMs) and release owners.

Principles

Some KPIs describe the outcome of an event, while others indicate a potential future result. At ELSP R&D, the focus is on KPIs that help to act in time to meet expected results.

Examples of different indicators.

KPIs on different levels

In ELSP, the overall focus is on on-time delivery, cost, quality, and innovation. In R&D, different levels contribute to this in their specific way:

The different levels with examples of what they measure and follow up.

Roles and responsibilities

The key roles involved with working with KPIs:

Quality team provides standard
- Provides standard KPI set.
- Provides standard discipline dashboard.
- Provides standard Power BI dashboard.
Release owner
- Proposes release-specific KPIs in the quality plan (QCM can help if needed). This includes adding/deleting KPIs as well as setting specific targets.
- Owns release-specific dashboards (QCM can help if needed).
- Reports data to the steering group.
Steering group
- Approves quality plan with KPIs.
- Decides on release, based on data provided.
Product owner / development teams
- Keep work item data updated.

Standard KPIs for releases

ID	Description	Motivation	Type	Target (recommended)	Measured (where/when)
M1	Completion (burndown) of system epics (System level)	To control release progress.	Scope	100% done at G5.	ADO (bi-weekly)
M2	System epics distribution per state (System level)	To control release progress.	Scope	No target, continuously monitored.	ADO (bi-weekly)
M3	Completion of epics by effort (burndown). This metric will add up the effort of underlying features which are not in closed/done state (Product level)	To control release progress.	Scope	100% done at M5.	Power BI R&D Dashboard / ADO (bi-weekly)
M4	Epics distribution by state and effort. For effort: this metric will add up the effort of underlying features (Product level)	To control release progress.	Scope	100% done at M5, continuously monitored.	Power BI R&D Dashboard / ADO (bi-weekly)
M5	Completion (burndown) of features (Product level)	To control release progress.	Scope	100% done at M5.	ADO (bi-weekly)
M6	Features list by states (Product level)	To control release progress.	Scope	No target, continuously monitored.	Power BI R&D Dashboard / ADO (bi-weekly)
M7	Completion of the scope bugs (Open Bugs Trend). Scope bugs: bugs detected in previous releases and targeted to be fixed in the current release (Product level)	To control release progress.	Scope	All bugs closed (fixed, will not fix, deferred, as design …) at M5.	Power BI R&D Dashboard / ADO (bi-weekly)
M8	Completion of the introduced bugs (Open Bugs Trend). Introduced bugs: bugs detected in the current release (Product level)	To follow up of introduced bugs in the release.	Quality	All bugs closed (fixed, will not fix, deferred, as design …) at M5.	Power BI R&D Dashboard / ADO (bi-weekly)
M9	Number of added/removed system epics after G2 (System level)	To follow up on scope volatility.	Scope	No target, continuously monitored.	ADO (bi-weekly)
M10	Number of added/removed epics after G2 (Product level)	To follow up on scope volatility.	Scope	No target, continuously monitored.	ADO (bi-weekly)
M11	Number of added/removed scope bugs after G2. Scope bugs: bugs detected in previous releases and targeted to be fixed in the current release (Product level)	To follow up on scope volatility.	Quality	No target, continuously monitored.	ADO (bi-weekly)
M12	Open bugs distribution per product, severity, state, how found (originator) (Product level)	To follow up on bug status.	Quality	No target, continuously monitored.	Power BI R&D Dashboard / ADO (bi-weekly)
M13	Bugs introduced by the release: inflow and remaining bugs shown by severity (Product level)	To follow up on bug status.	Quality	>2 weeks of decreasing trend (inflow and open bugs) during active testing before setting M5.	Power BI R&D Dashboard / ADO (bi-weekly)
M14	Number of critical and high bugs not fixed (implemented and integrated in build) at M4 (Product level)	To follow up on bug status.	Quality	0	Power BI R&D Dashboard / ADO (bi-weekly)
M15	Number of deferred bugs. Metric should be available for all bugs, scope bugs and introduced bugs (Product level)	To follow up on bug status.	Quality	No target, continuously monitored.	Power BI R&D Dashboard / ADO (bi-weekly)
M16	Product test (PT) status: total, passed, failed and blocked. Metric should be able to be sliced on unique test points and all test points (Product level)	To follow up on status of PT.	Quality	0 blocked by M4; 0 blocked by M5; 0 failed test cases not properly addressed/tracked (release notes, test report…) at M5.	Power BI R&D Dashboard / ADO (bi-weekly)
M17	System test (ST) status: total, passed, failed and blocked. Metric should be able to be sliced on unique test points and all test points (System level)	To follow up on status of ST.	Quality	0 blocked by G4; 0 blocked by G5; 0 failed test cases not properly addressed/tracked (release notes, test report…) at G5.	Power BI R&D Dashboard / ADO (bi-weekly)
M18	Unit test coverage (on new and changed code) (Product level)	To follow up on code quality.	Quality	>80%	SonarQube or similar (bi-weekly)
M19	Static code analysis coverage (%) (Product level)	To follow up on code quality.	Quality	100%	SonarQube or similar (bi-weekly)
M20	Fix rate of static code analysis warnings/errors (%) (Product level)	To follow up on code quality.	Quality	>80%	SonarQube or similar (bi-weekly)
M21	Data quality dashboard: missing data, parent-child relationship issues, open items in old iterations (System level and Product level)	To follow up on process adherence.	Quality	Green (no errors).	ADO (bi-weekly)
M22	Monthly spending (System level and Product level)	To control budget.	Cost	According to budget.	SAP (monthly)
M23	Gate/MS on time (System level and Product level)	To control time schedule.	Time	100%	SAP (monthly)
M24	Epics/features test coverage by product tests. This metric will look for linked test cases in ADO. The epic pie chart will account for underlying features (Product level)	To follow up test quality.	Quality	>85%	Power BI R&D Dashboard / ADO (bi-weekly)
M25	Epics/features test coverage by system tests. This metric will look for linked test cases in ADO. The epic pie chart will account for underlying features (System level)	To follow up test quality.	Quality	>85%	Power BI R&D Dashboard / ADO (bi-weekly)
M26	Product tests automation coverage (Product level)	To follow up test quality.	Quality	>80%	Power BI R&D Dashboard / ADO (bi-weekly)
M27	System tests automation coverage (System level)	To follow up test quality.	Quality	>80%	Power BI R&D Dashboard / ADO (bi-weekly)
M28	System Integration Test Automation coverage	To follow up test quality.	Quality	>80%	Power BI R&D Dashboard (bi-weekly)
M29	Security vulnerabilities: number of security vulnerabilities (SonarQube, BlackDuck, DSAC, Bugs)	To follow up on code quality.	Quality	0 (zero) unreviewed bugs at M5 or component release	Azure DevOps (dashboard + release pipeline gates, bi-weekly)
M30	Bug answering performance: the answer time needed to set a bug to the “Closed” status from the moment it is received. It is measured in order to keep bug backlog under control.	To follow up on bug status.	Quality	0 bugs older than 3 months	Azure DevOps (bi-weekly)
M31	Critical, high severity and priority 1 bug handling: important defects are resolved in a timely manner.	To follow up on bug status.	Quality	0 Critical, High or Prio 1 bugs are older than 2 weeks	Azure DevOps (bi-weekly)
M32	Bug leakage from development: customers, Pilots, FI-STT and SIT are finding % of bugs that were supposed to be caught by a previous level of testing (development teams).	To follow up on bug status.	Quality	<10%	Azure DevOps (bi-weekly)

References

PCP R&D Quality Dashboards Quality Plan Discipline Dashboard PCP Analytics Portal Info Page - Power BI PCP R&D SPI KPI

R&D Quality Criteria

Mon, 01 Jan 0001 00:00:00 +0000

The “R&D Quality Criteria” is a tool and checklist for Quality Control Managers (QCM), and is used to plan quality audits and assessments for project milestones and report quality status.

This Quality Checklist is a summary of ABB R&D milestone checklist items at each main project milestone:

M2 Quality Criteria
M3 Quality Criteria
M4 Quality Criteria
M5 Quality Criteria
M6 Quality Criteria

The quality criteria shall be checked by QCM before each required milestone. RO and CM support with the necessary information to help QCM perform the quality assessment.

The respective gaps and findings shall be analyzed and listed in a Quality Report by QCM and communicated to relevant stakeholders.

For release aspects (alpha, beta, etc.), see Release Stages Guide.

M2

Development status

System/Technology Requirements are approved.
System epics are approved (Including epic links and area path).
Epics are agreed upon (including description, acceptance criteria, high-level estimate, target date and area/iteration path).
A “baseline” of the agreed system epics, epics, and scope bugs is created (M2 agreement).
Implementation Proposals (if needed) are approved.
Safety: Product and Safety Requirement Specifications are approved.
Safety: Safety System Architecture, System FMEA, Preliminary Hazard Report, and Tool Selection Report are created and approved.
Safety: System Software Critically analysis and Impact Analysis Report are created (draft).

Test status

The Product Test Strategy and Plan is approved.
The Product Test plan/Test suites high level plan created in ADO.
A method of ensuring planned requirements are developed and tested is established (method for requirements traceability).

Bug status

A “baseline” of the agreed scope bugs exist (see development status).

Release status

Project Description and Plan created and approved (including scope and capacity plan).
Quality Plan including KPIs is created and approved.
Dashboards are created.
Configuration Management Plan is created and approved.
Names on RACI is created and approved.
A Document Control Plan is created (draft)
User Document Control Plan is created (draft).
The Cyber Security preliminary assessment is done.
Already known new or modified 3rd party software is updated in DFN (draft).

M2 status

M2 is planned and the R&D checklist is up to date.
All previous remarks resolved or accepted and resolution planned.

System status

System Test Strategy and Plan is documented and agreed upon.
System Test plan/Test suites high level plan created in ADO.
System Integration Plan is approved, and milestones are derived.
A beta site delivery plan is created.

M3

Development status

Drafts of key technical documentation, like architecture, threat model, design and interface exist.
Change requests of system requirements completed for any changes in scope since M2.
Epics/feature progress is on target to be completed by the planned date.
DoD of closed epics/features has been applied.

Test status

Product integration and test (PIT) is progressing and showing good quality of deliveries.

Bug status

Bugs of severity critical and high are under control (a reasonable amount).
Scope bug progress is on target to be completed by the planned date.
Introduced bugs are being fixed as they are found, backlog is not continuously growing.

Release status

Documentation is up to date.
Quality dashboard reviewed (KPI & Data quality).

M3 status

M3 is planned and the R&D checklist is up to date.
All previous remarks resolved or accepted and resolution planned.

System status

Change requests of system requirements completed for any changes in scope since G2.
System epics progress is on target to be completed by the planned date.
DoD of closed system epics has been applied.
System integration and test (SIT) is progressing and showing good quality of deliveries.

M4

Development status

All software and hardware functionality (including change requests and scope bugs) are implemented.
The design documentation is reviewed and approved. Consider software, hardware, firmware, cyber security, etc.
Safety: safety-related documents like architecture model, Hazop, and FMEA are updated and approved.

Test status

Unit tests and component tests (e.g, MT/DT/FT/CT) are finalized. Related test descriptions are approved, tests executed and test reports are approved.
Product integration and test (PIT) completed.
Product type test (PTT) descriptions are reviewed and approved (ready for the start of PTT).
The product has achieved beta status. That is, the beta criteria are fulfilled, documented, and the decision meeting was held.
Pre-DSAC has been successfully completed, findings are documented in ADO.
Safety: SVT descriptions are reviewed and approved (ready for the start of formal tests).
Hardware: Environmental tests (ET) are executed. Related test descriptions are approved, tests executed, and test reports are available.

Bug status

Bugs of severity critical are investigated and corrected.
Bugs of severity high have been investigated, analyzed, and selected for implementation or deferral.
The number of bugs that have not reached successful validation yet (closed state) is reasonable.
The number of critical and high-severity bugs reported by week is declining.

Release status

User manuals have been updated (draft). User manuals with new functionality have been reviewed at least once.
A draft of the Release Note is available.
OSS Scan is done, reports are received and there are work items in place to mitigate eventual findings.
The Cyber Security assessment is done and reviewed with Cyber Security Team, and there are work items in place to mitigate eventual findings.
The list of 3rd party software in use is updated and approved in DFN.
Quality dashboard reviewed (KPI & Data quality).

M4 status

M4 is planned and the R&D checklist is up to date.
All previous remarks resolved or accepted and resolution planned.

System status

System Test plan/Test suites are reviewed and approved.
System test strategy and plan updated, reviewed, and approved.
System integration and test (SIT) completed.
The checklist for the start of STT is approved, and the meeting was held. Ready to start STT in all products and test benches.
User manuals have been updated (draft). User manuals with new functionality have been reviewed at least once.
The NLS project (if any) has passed M2.

M5

Development status

All planned work items (scope backlog, requirements, scope bugs, and change requests) are implemented and validated.
Safety: the impact analysis reports are reviewed and approved.

Test status

PTT is finalized. Tests are executed and test reports are approved.
The requirements-test traceability is in place (as per the method defined in M2). Test coverage can be demonstrated.
DSAC has been successfully completed, findings are documented in ADO.
Safety: SVT is finalized. Tests are executed, test reports are approved, and CoT is done.

Bug status

Bugs of severity critical are investigated, corrected, and validated.
Bugs of severity high, medium, and low have been investigated and are a) implemented and validated or b) deferred (dispositioned and justified by CCB).

Release Status

All user manuals are reviewed and approved.
The Release Note is reviewed and approved.
The Cyber Security assessment is approved, including approval of all exceptions.
The OSS scanning is completed, and all exceptions are accepted.
The 3rd party software in use is approved, and all exceptions are accepted.
FCA and PCA are performed, and reports are approved.
Quality dashboard reviewed (KPI & Data quality).

M5 status

M5 is planned and the R&D checklist is up to date.
All previous remarks resolved or accepted and resolution planned.

System status

STT is finalized. Tests are executed and test reports are approved.
The RAT checklist is completed and approved.
RAT is finalized. Tests are executed and test reports are approved.
The IVA checklist is completed and approved.
The status of system requirements validation is clear (passed/failed/not done).
ST recommendations for the system for release are given. Recommendations and any remarks by STT are documented.

M6

Development status

Test status

Bug status

Release status

Final report is approved.
Document Control Plan up to date.
User Document Control Plan approved.
Stand-alone deliveries (if any are planned at M2) are finalized.
Quality dashboard reviewed (KPI & Data quality).

M6 status

M6 is planned and the R&D checklist is up to date.
No old remarks remain.

System status

The NLS project has passed M5.

References

Quality Process Quality Templates Integrated Project Management

Recommended Component Test Frameworks

Mon, 01 Jan 0001 00:00:00 +0000

The following component test frameworks are recommended but not mandatory.

GoogleTest

Used for example in the Control Software stream, e.g. for Next Generation control development. The format is XML because there is an own-developed test framework on top of the GoogleTest framework that processes an XML-format file as input.

Example of a component test:

<TestCases>
 <!-- Each TestCase needs a unique Id number -->
 <TestCase Id="1"> <!-- Description if the test case. -->
 <Documentation>
 <Description>
 Configure an empty Ac800m configuration service and the AlarmAndEvent service lib with condition
 files at startup, then do a reconfiguration. Alarm conditions are activated and deactivated
 cyclically from code.
 </Description>
 <Setup>Correct configuration files are used to configure Ac800m and AlarmAndEvent.</Setup>
 <ExpectedResult>
 Ac800m and AlarmAndEvent register and unregister the alarm conditions correctly. The alarm conditions
 are toggled between activated and deactivated.
 </ExpectedResult>
 </Documentation>

 <!-- START OF CONFIGURATION -->
 <!-- Operation: AddControlService: add service to start list -->
 <TestStep Operation="AddControlService"> <!-- Add the service for Execution service -->
 <Parameter Name="InstanceName" Value="AC800MExecService" />
 <Parameter Name="DefaultConfig" Value="0001_AEConditions/AEConditions_ConfigCollection.xml" />
 </TestStep>

 <!-- Operation: Start: start the platform with the given start list. -->
 <TestStep Operation="Start" />

 <!-- START OF SUCCESSFUL RECONFIGURATION -->
 <TestStep Operation="HighlevelConfig">
 <Parameter Name="Operation" Value="Connect" />
 <Parameter Name="OPCUAurl" Value="[ConfigMgrDefaultUrl]" />
 </TestStep>

 <TestStep Operation="HighlevelConfig">
 <Parameter Name="Operation" Value="OpenConfigCollection" />
 <Parameter Name="ClientNumber" Value="0" />
 <Parameter Name="ReceiverID" Value="AC800MExecService" />
 </TestStep>

 <TestStep Operation="HighlevelConfig">
 <Parameter Name="Operation" Value="TransferCollectionFile" />
 <Parameter Name="ClientNumber" Value="0" />
 <Parameter Name="CollectionNumber" Value="1" />
 <Parameter Name="ManifestPath" Value="0001_AEConditions/AEConditions_ConfigCollection.xml" />
 <Parameter Name="FilePath" Value="0001_AEConditions/AEConditions.signals.xml" />
 <Parameter Name="FilePath" Value="0001_AEConditions/AEConditions.conditions.xml" />
 <Parameter Name="FilePath" Value="0001_AEConditions/AEConditions.ncac.xml" />
 <Parameter Name="FilePath" Value="0001_AEConditions/AEConditions.ncos.xml" />
 <Parameter Name="FilePath" Value="0001_AEConditions/AEConditions.task.xml" />
 </TestStep>

 <TestStep Operation="HighlevelConfig">
 <Parameter Name="Operation" Value="PrepareConfigCollection" />
 <Parameter Name="ClientNumber" Value="0" />
 <Parameter Name="CollectionNumber" Value="1" />
 </TestStep>

 <TestStep Operation="HighlevelConfig">
 <Parameter Name="Operation" Value="CommitAndCloseConfigCollection" />
 <Parameter Name="ClientNumber" Value="0" />
 <Parameter Name="CollectionNumber" Value="1" />
 </TestStep>

 <TestStep Operation="HighlevelConfig">
 <Parameter Name="Operation" Value="Disconnect" />
 <Parameter Name="ClientNumber" Value="0" />
 </TestStep>
 <!-- END OF SUCCESSFUL RECONFIGURATION -->

 <!-- Operation: VerifyLog: inspect log files. -->
 <TestStep Operation="VerifyLog">
 <!-- Find text (with regex) on any row in log file -->
 <Parameter Name="LogFolder" Value="AC800MExecService" />
 <!-- DbgPrint Id=5 v1=1 v2=0 -->
 <Parameter Name="Text" Value="AEConditionManager::RegisterCondition: size=0, and inputSize=2." />
 <Parameter Name="Text" Value="AEConfigurableComponent::EndCommit completed." />
 <Parameter Name="Text" Value="AEConditionManager::RegisterCondition: size=2, and inputSize=2." />
 <Parameter Name="Text" Value="AEConfigurableComponent::EndCommit completed." />

 <Parameter Name="Text" Value="CEN: SN:alarm1_SrcName / CN:alarm1_CondName / Active:true" />
 <Parameter Name="Text" Value="CEN: SN:alarm1_SrcName / CN:alarm1_CondName / Acknowledged:true" />
 <Parameter Name="Text" Value="CEN: SN:alarm1_SrcName / CN:alarm1_CondName / Retain:true" />
 <Parameter Name="Text" Value="CEN: SN:alarm1_SrcName / CN:alarm1_CondName / ConditionId:\'-AEConditions.Program1.alarm1Obj\'" />

 <Parameter Name="Text" Value="CEN: SN:alarm2_SrcName / CN:alarm2_CondName / Active:true" />
 <Parameter Name="Text" Value="CEN: SN:alarm1_SrcName / CN:alarm1_CondName / Acknowledged:true" />
 <Parameter Name="Text" Value="CEN: SN:alarm2_SrcName / CN:alarm2_CondName / Retain:true" />

 <Parameter Name="Text" Value="CEN: SN:alarm1_SrcName / CN:alarm1_CondName / Active:false" />
 <Parameter Name="Text" Value="CEN: SN:alarm1_SrcName / CN:alarm1_CondName / Acknowledged:true" />
 <Parameter Name="Text" Value="CEN: SN:alarm1_SrcName / CN:alarm1_CondName / Retain:false" />

 <Parameter Name="Text" Value="CEN: SN:alarm2_SrcName / CN:alarm2_CondName / Active:false" />
 <Parameter Name="Text" Value="CEN: SN:alarm1_SrcName / CN:alarm1_CondName / Acknowledged:true" />
 <Parameter Name="Text" Value="CEN: SN:alarm1_SrcName / CN:alarm1_CondName / Retain:false" />

 <Parameter Name="Text" Value="AEConditionManager::UnregisterCondition: size=4 and inputSize=2." />
 <Parameter Name="Text" Value="AEConfigurableComponent::CleanupConfigInternal completed." />
 </TestStep>

 <!-- Operation: Stop: halt platform and ApplicationServices -->
 <TestStep Operation="Stop" />
 </TestCase>
</TestCases>

MSTest

Used for example in the Operations stream for Symphony Plus, e.g. in backend services written with C++ and C#.

Example of a C#/C++ test to write and read a tag:

[TestMethod]
public void ItemsReadWrite(int newValue)
{
 // Assert.
 Assert.IsTrue(CReadWriteField::TestSetAndGet(newValue));
 Console.WriteLine("Test finished.");
}

bool CReadWriteField::TestSetAndGet(int newValue)
{
 CString strLogMessage;
 // Prepare to Set new info
 TAGINFOEX tInfo;
 SetTagInfo(tInfo, _tVt, newValue);

 DWORD dwSubParam = SetSubParam(_tType);

 // Notice: tInfo is not preserved by all settings. need to have a copy
 TAGINFOEX eInfo = tInfo;

 bool bRet = _si->SetInfo(_tType, &tInfo.info, 0, dwSubParam);
 if (!bRet)
 {
 if (_paramConfig)
 {
 ApiTestUtil::Message(L"%s.%s - Set Info failed\n", _si->GetName().c_str(), _paramName);
 return false;
 }
 }
 else
 {
 if (!_paramConfig)
 {
 ApiTestUtil::Message(L"%s.%s - Set Info suceeded but not flagged as config\n", _si->GetName().c_str(), _paramName);
 }
 }

 // Wait for Data Processing (if any is requested)
 if (_tVt == vt_TVX)
 {
 Sleep(1000);
 }

 // Read back and compare
 PwInfo rInfo = _si->GetInfo(_tType, dwSubParam);
 if (rInfo.GetVarDataType() == vt_UNDEF)
 {
 ApiTestUtil::Message(L"%s.%s - read back failed\n", _si->GetName().c_str(), _paramName);
 return false;
 }

 TAGINFOEX rrInfo(*rInfo.GetTaginfo(), rInfo.GetVarDataType());
 if (!CompareInfo(_tType, rrInfo, eInfo))
 {
 ApiTestUtil::Message(L"%s.%s - comparison failed. Is %s - expected %s\n",
 _si->GetName().c_str(), _paramName, rInfo.ToString().c_str(), eInfo.ToString().c_str());
 return false;
 }
 return true;
}

Manual tests

Manual test cases are rare in software unit and component tests.

In cases they are needed, they should be defined in Test Case work items and be part of a Test suite in Azure DevOps. When the manual test cases are being performed, execution of the Test suite should be triggered so that the test result is registered directly in Azure DevOps together with the result of the automated tests.

To do this, manual tests and recording of the test results for each test step can be done using Microsoft Test Runner (which will be started automatically when you trigger the execution of test points in your test suite defined in Azure).

You can run tests for both web applications and desktop apps. For more details, check Microsoft’s guides: Run manual tests

Recommended Extensions

Mon, 01 Jan 0001 00:00:00 +0000

This page contains a list of Azure DevOps extensions that are pre-approved for use in PCP.

If you wish to start using an extension, please contact your Configuration Manager or Quality Control Manager first.

It is possible to request a new extension with a Process Change Request.

The request will be evaluated by the Configuration Management process group and possibly other groups as needed. After the extension has been approved, the CM will contact an Azure DevOps Collection Admin with sufficient permissions to install the extension.

Extension	Description	Resources
Retrospectives (Microsoft DevLabs)	Extension to do retrospective sessions and track actions, especially useful when collaborating remotely	Marketplace link
Estimate (Microsoft DevLabs)	Planning Poker estimation extension	Marketplace link Training slides
Appgami Checklist (Appgami)	Auto-population of checklist and track progress on Work item form	Marketplace Link Demo
Generate Release Notes (Crossplatform)	This extension generates a release notes file based on a user defined Handlbars template. It can be used inside any Azure DevOps Classic Build, Classic Release or Multistage YAML Pipeline.	Marketplace Link containing extensive documentation and examples
Code signing with Software Trust Manager	DigiCert® Secure Software Manager automates code signing workflows, improving software security and integrating seamlessly with DevOps processes. Secure Software Manager client tools enable developers to sign binaries with signing tools on a wide range of platforms securely and efficiently. Secure Software Manager client tools extension expedite the installation and setup of client and signing tools to get developers signing-ready fast in Azure hosted environment.	https://marketplace.visualstudio.com/items?itemName=Digicert.ssm-client-tools-extension
PublishHTMLReports	This extension publishes any .html report to Build Pipeline and it is immensely useful and easy to read for most of our stakeholders in a single view of the pipelines result, quite user friendly	Marketplace link
Jupyter Notebook (Microsoft DevLabs)	Render your .ipynb notebook files directly in Azure DevOps	Marketplace link
Allure Report Viewer	This Azure DevOps extension provides a task for publishing an allure report by inlining all related files and embedding it into a Build and Release page as separate tab	Marketplace link
POSTMAN Report	This Azure DevOps extension provides task for Publishing Postman / Newman HTML Reports into built into Azure Storage	Marketplace link
Newman the cli Companion for Postman	This extension helps to effortlessly run and test a Postman Collections directly from the command-line and in a task	Marketplace link
Wiql Editor	Search work items with the expressiveness of the work item query language. Explore the wiql syntax on the wiql playground. This extension helps to define WIQL queries, that support more operators than normal queries, for example ASOF for historical queries.	Marketplace link
Terraform (Microsoft DevLabs)	Terraform extension by MicrosoftDevLabs that supports “Infrastructure as Code” to define and provision infrastructure using a high-level configuration language	Marketplace Link Training recording
OpenShift (Red Hat)	This Azure DevOps extension offers tasks for integrating OpenShift into your build and release pipelines, for example by executing user defined oc commands.	Marketplace Link
Multivalue control (Microsoft DevLabs)	This extension provides a custom control for work items to define a field with multiple values. This is used by AV to implement Target System Release.	Marketplace link
Invicti Enterprise (Invicti Ltd)	Invicti Enterprise is an automated, yet fully configurable, web application security scanner. It enables you to scan websites, web applications, and web services identify security flaws. Invicti can scan all types of web applications, regardless of the platform or the language with which they are built.	Marketplace link
CloneBug	This is an extension that enables users to easily clone Bugs within ABB PCP Azure environment and automatically create links and copy/clean decided attributes to new workitem. This extension is only visible to specified organizations/collections and requests to add new organizations/collections can be done by placing a PCR to Configuration Management process team	Marketplace link
Dependabot	This extension enables users to run Dependabot inside a build pipeline in Azure DevOps	Marketplace link

Recommended Settings for Feeds

Mon, 01 Jan 0001 00:00:00 +0000

Each feed created in an organization is highly recommended to use the below settings. Below recommended settings are based on the need for development and cost estimate for ABB.

“Feed Details” page

Configuration name	Value / Setting
Hide deleted package versions	“Activated” “Ticked”
Enable package badges	“Activated” “Ticked”
Enable package retention	“Activated” “Ticked”
Maximum number of versions per package	12
Days to keep recently downloaded packages	30

A package promoted from local will not be counted in the
12 versions to keep, i.e., packages in views "Pre-Release"
or "Release" is not counted towards these 12 versions.
If version 13 (and upwards) is in a package that has not been
downloaded the last 30 days will be deleted (both criteria
needs to be fulfilled for a version to be deleted).

“Permissions” page

User/Group	Role	Inherited
[<“Project name”>]\Contributors	Contributor

All others default

“Views” page

View	Access Permissions	Default view
Local	Feed users
Prerelease	Feed users; All feeds and people in <“your organization name”>	“Activated” “Ticked”
Release	Feed users; All feeds and people in <“your organization name”>

“Upstream sources” page

"Empty" - No upstream sources configured
Or
Use upstream feeds as needed for your project.

Recommended Unit Test Frameworks

Mon, 01 Jan 0001 00:00:00 +0000

The following unit test frameworks are recommended but not mandatory.

GoogleTest

Used for example in the Control Software stream, e.g. for Next Generation control development using C++.

Example of a unit test:

TEST(GTestCaseClass, TestFibonacci) {
 TEST_ID("001");
 TEST_DESCRIPTION("Test of Fibonacci property");
 TEST_EXPECTED_RESULT("The correct fibonacci number is returned for position 1-3.");

 // Setup
 EngineerSw engineer = EngineerSw(1);

 // Test and verify
 // Stops current function.
 // Use when continuing after failure doesn't make sense
 ASSERT_EQ(1, engineer.fibonacci(1));

 // Use when you want the test to continue to reveal more errors after the assertion failure
 EXPECT_EQ(1, engineer.fibonacci(2));
 EXPECT_EQ(2, engineer.fibonacci(3));
}

xUnit

Used for example in the Operations stream for Next Generation HMI development, e.g. in backend services written with C#.

Example of a unit test:

[Fact]
public void GetBinGraphic200_Test()
{
 // Arrange
 var filename = "test";
 var binGraphic = new BinGraphic() { Name = "test", BinGraphicStream = new byte[0] };
 this.DbContext.BinGraphics.Add(binGraphic);
 this.DbContext.SaveChanges();
 var expected = new MemoryStream(binGraphic.BinGraphicStream, 0, binGraphic.BinGraphicStream.Length);

 // Act
 var controller = new LooxWasmController(logger, this.DbContext, this.testValuesSource.Object, simulationConfig);
 var resultAPI = controller.GetBinGraphic(filename) as FileStreamResult;
 var result = new MemoryStream();
 resultAPI.FileStream.CopyTo(result);

 // Assert
 Assert.True(expected.ToArray().Equals(result.ToArray()));
}

Jest

Used for example in the Operations stream for Next Generation HMI development, e.g. in frontend services written with Typescript Javascript.

Example of a unit test:

describe('LooxAPIService', () => {
 test('Should correctly fetch graphics list', async () => {
 // Arrange and Act
 looxService.url = "test";
 let graphicsList = await looxService.getGraphicsList();

 // Assert
 expect(graphicsList).toEqual(lastFetch);
 });

MSTest

Used for example in the Operations stream for Symphony Plus, e.g. in backend services written with C#.

Example of a unit test:

[TestMethod]
[Description("Check Quality is expected")]
public void SamplingListTest_AverageQuality()
{
 //PREPARATION
 DateTime normalizeddt = DateTime.UtcNow;
 normalizeddt = normalizeddt.AddSeconds(-normalizeddt.Second);

 List<SPlusValue> values = new List<SPlusValue>();
 SPlusValue testvalue = new SPlusValue
 {
 Dt = normalizeddt.AddMinutes(-5),
 Value = 1,
 Qual = SPlusQuality.Channelfailure
 };
 values.Add(testvalue);
 testvalue = new SPlusValue
 {
 Dt = normalizeddt.AddMinutes(-3),
 Value = 1000,
 Qual = SPlusQuality.Good
 };
 values.Add(testvalue);

 //ACT - FUNCTION TO BE TESTED
 List<SPlusValue> t = SamplerGenerator.AverageSamplingList(values, normalizeddt.AddMinutes(-6), normalizeddt.AddMinutes(-1), 300);

 //ASSERT
 Assert.AreEqual(t?[1]?.Qual, SPlusQuality.Channelfailure);
}

Release Stages

Mon, 01 Jan 0001 00:00:00 +0000

This guide provides insights and definitions for the various release stages of a component, function, product, or system.

Introduction

During the development of new products, functions, or components, release stages are used to describe the level of maturity of the coming release. The release stages are alpha, beta candidate, beta, release candidate, and release.

Release stages - overview

The table below gives an overview of the maturity level and use of the different release stages.

Alpha	Beta candidate	Beta	Release candidate	Release
- Functionality not complete - Not fully tested	- (Close to) full functionality - Component and product test initiated - User documentation available as drafts	- Full functionality - Component test completed - Partly product/system tested	- Product version aimed to be released - Formal product and system tests executed	- Final version, market release - Release acceptance test - Safety validation test (for safety products) - Media verification
- Early integration & testing (no external distribution).	- Internal interim use - External test labs	- Formal product/system test - At selected beta sites.	- Final tests (no major changes expected ahead)	- Release

In Azure DevOps (ADO), there are “only” three artifacts relating to the maturity level of a release, mapping to the release stages like this:

Artifact in Azure DevOps	Release stage
- Local	- Unclassified (e.g. daily build, pull request) - Alpha
- Prerelease	- Beta candidate - Beta - Release candidate
- Release	- Release

Release stages - descriptions

Alpha version (α)

An alpha (α) version is a pre-release version where functionality is not complete, and not fully tested. A clear description in the “version notes” (or similar) of which functionality is available, and which is not available, is required.

Alpha quality in a function/component is not sufficient to permit distribution to external customers or users. An alpha version is used by other functions/components and products under development, for early integration and testing.

Beta Versions

There are two beta definitions: beta candidate and beta. Both are pre-release versions. The criteria for acceptance of the two beta versions are described in the following sections. The main differences between beta candidate and beta are described in the table below:

Beta candidate	Beta
A beta candidate has full functionality, or close to full functionality. In cases when some functionality is missing, it should be well defined.	A beta always has full functionality.
Beta candidates are intended for interim use as “internal betas”. They may also be used by internal/external test labs to build up a system environment when testing products and systems.	A beta has higher quality level than a beta candidate and has undergone a longer test time, see 3BSE061530 Checklist for Beta, IVA, and STT.xlsx for details.
A beta candidate may in restricted cases be used at beta sites in limited and non-critical areas, for example during engineering work at a customer site.	A beta may be used for shipments to defined beta sites.

Beta candidate version of a product (βC)

A beta candidate version of a product (e.g. stand-alone product, product part of a system, or a system) has full functionality, or close to full functionality. A formal decision is required if the product is in the beta candidate stage or not, documented in the beta checklist 3BSE061530 Checklist for Beta, IVA, and STT.xlsx.

The following criteria define the quality expected for the beta candidate release stage of a product:

The product has full functionality, or close to full functionality according to the requirements and epics. In case of missing functionality, the scope of included and missing functionality in the beta candidate shall be well-defined and documented in “version notes” (or similar).
A formal component test has been executed.
An informal product test has been executed.
Integration tests have been executed, including tests with other dependent products (if applicable).
Hardware: informal hardware and firmware tests have been executed.
User documentation, including the installation guide, is available as drafts.

Beta version of a product (β)

A beta version of a product (e.g. stand-alone product, product part of a system, or a system) has full functionality. A formal decision is required if the product is in the beta stage or not, documented in the beta checklist 3BSE061530 Checklist for Beta, IVA, and STT.xlsx.

The following criteria define the quality expected for the beta release stage of a product:

The product has full functionality according to the requirements and epics.
All the above quality criteria for beta candidate versions are fulfilled.
Digital code signing: the product is release signed (using external certificates).
Pre-DSAC has been executed with findings documented and accepted.
3rd party software OSS scan has been executed with findings documented and accepted.
Cyber security assessment executed with findings documented and accepted.
An informal product test has been executed with findings documented and accepted.
An informal system test has been executed with findings documented and accepted.
Start of product type test criteria are fulfilled 3BSE061530 Checklist for Beta, IVA, and STT.xlsx.
Start of system type test criteria are fulfilled (if applicable) 3BSE061530 Checklist for Beta, IVA, and STT.xlsx.

To increase the test coverage, beta versions can be shared with customers who are selected as beta sites. Note that shipment of beta versions to customers shall always be done with the expressed understanding by the customer that the product is a beta version and any tests shall be executed in accordance with any beta test program instructions and shall be subject to conditions of use as described in a signed beta test agreement [2].

Release candidate versions (RC & RC HI)

A release candidate (RC) is the product version that is aimed to be released either as part of a system release or as a stand-alone product. All type tests are finished except the specified release acceptance test (RAT), standard regression test (SRT), and safety validation test (SVT).

Release candidate high integrity (RC HI) is a proposed safety product version and in addition to the quality requirements for a release candidate shall also fulfill the quality requirements covered by the checkpoint for SVT (checklist for “start of test” is fulfilled, see ref. 3BSE061530 Checklist for Beta, IVA, and STT.xlsx).

A formal decision is required if the product is in the release candidate stage or not, documented in the “Start of RAT” checklist 3BSE061530 Checklist for Beta, IVA, and STT.xlsx.

The following criteria define the quality expected for the release candidate stage of a product:

The product has full functionality according to the requirements and epics.
All the above quality criteria for beta candidates and beta versions are fulfilled.
DSAC has been executed.
A formal product test has been executed.
A formal system test has been executed.
“Start of RAT” criteria are fulfilled 3BSE061530 Checklist for Beta, IVA, and STT.xlsx.

Release version

The release version is the final version ready for market release. A formal decision is required if the product is ready for market release, documented in the internal validation acceptance (IVA) checklist 3BSE061530 Checklist for Beta, IVA, and STT.xlsx.

The following criteria define the quality expected for the release version of a product:

All the above quality criteria for beta candidate, beta and release candidate versions are fulfilled.
IVA criteria are fulfilled 3BSE061530 Checklist for Beta, IVA, and STT.xlsx.

Criteria for external delivery

A beta version or a release candidate version may be used for shipments to defined beta sites. Also, a beta candidate may in restricted cases be used at beta sites in limited and safe areas, for example during engineering work at a customer site.

An external delivery outside R&D (to divisions or end customers) can have different designations, depending on the quality level, the targeted audience, and intended usage.

The following criteria define the quality expected for an external delivery of a product:

The above quality criteria for beta versions are fulfilled (or non-fulfilled items are accepted).
Quality for beta shipment is fulfilled (verified through e.g. installation test, regression test, and specific customer use case tests)
3rd-party software approved, OSS obligations fulfilled.
Pre-DSAC has been executed.
Export control classification (ECCN) approved.
License handling: license/license file available for the receiver (e.g. demo license)
Virus scanning (using virus scanners according to defined requirements).
Hardware modules marked as beta components (e.g. non-removable marking/sticker).
Ex: components to be Ex-certified must not have Ex-marking until the Ex-certification is granted.
Safety: high integrity controller firmware shall either not be part of the delivery (for non-HI projects), or NON-CERT-marked (for HI projects). (CERT-marked controller firmware is only allowed to be distributed after explicit approval from the assessor).
Beta indication/marking in software in about boxes, logs, and user interfaces (if applicable).
Support strategy defined, and support organization trained.
A beta agreement has been signed by the external receiver and by the internal accountable.
“PA PCP Early Delivery” delivery request approved.
HW delivery: Each component serial number is documented and stored in the “PA PCP Early Delivery” SharePoint site PA PCP Early Delivery - SharePoint site.
Software uploaded to the “PA PCP Early Delivery” -site.

Release stage definitions

The figure below shows the evolution of the different release stages throughout the project lifecycle and the alignment between the release stages and test phases. This defines the criteria for each release stage. However, it is allowed to fulfill release stage criteria in an earlier stage, or in a combined release stage, which can be the case for products not part of a system, and products developed in a fully agile environment. If a product is released without going through the stages separately, all applicable release stage criteria must still be fulfilled before release.

Each of the release stages is subject to the configuration change control process. Any changes made in a version such as a defect correction or improved functionality shall be handled as described in the process for configuration change control.

References

SE061530 Checklist for Beta, IVA, and STT.xlsx SR000887 FIELD BETA - TEST AGREEMENT PCP Early Delivery - SharePoint site

Scrum

Mon, 01 Jan 0001 00:00:00 +0000

Scrum is a framework used by teams to manage their work. Scrum implements the principles of Agile as a concrete set of artifacts, practices, and roles.

The Scrum lifecycle

The following diagram details the iterative Scrum lifecycle. The entire lifecycle is completed in a fixed time box called a sprint. The sprint is typically 2-4 weeks long.

Scrum Roles

Scrum prescribes three specific roles.

Product Owner

Responsible for what the team is building and why they are building it. The product owner is responsible for keeping the backlog up-to-date and in priority order.

Scrum Master

Responsible to ensure the scrum process is followed by the team. Scrum masters are continually on the lookout for how the team can improve while also resolving impediments (blocking issues) that arise during the sprint. Scrum masters are part coach, part team member, and part cheerleader.

Scrum Team

These are the individuals that build the product. The team owns the engineering of the product and the quality that goes with it.

Product Backlog

The Product Backlog is a prioritized list based on the value the team can deliver. The Product Owner owns the backlog and adds, changes, and reprioritizes as needed. The items at the top of the backlog should always be ready for the team to execute.

Sprint Planning and Sprint Backlog

In Sprint Planning, the team chooses the backlog items they will work on in the upcoming sprint. The team chooses backlog items based on priority and what they believe they can complete in the sprint. The Sprint Backlog is the list of items the team plans to deliver in the sprint. Often, each item on the Sprint Backlog is broken down into tasks. Once all members agree that the Sprint Backlog is achievable, the sprint starts.

Sprint Execution and Daily Scrum

Once the sprint starts, the team executes the Sprint Backlog. Scrum does not specify how the team should execute. That is left for the team to decide.

Scrum defines a practice called a Daily Scrum, often called the Daily Standup. The Daily Scrum is a daily meeting limited to 15 minutes. Team members often stand during the meeting to ensure it stays brief. Each team member briefly reports their progress since yesterday, the plans for today, and anything impeding their progress.

To aid the Daily Scrum, teams often review two artifacts:

The Task Board

The task board lists each backlog item the team is working on, broken down into the tasks required to complete it. Tasks are placed in “To do”, “In progress”, and “Done” columns based on their status. It provides a visual way of tracking progress for each backlog item.

The Sprint Burndown

The sprint burndown is a graph that plots the daily total of remaining work. The remaining work is typically in hours. It provides a visual way of showing whether the team is on track to complete all the work by the end of the sprint.

Sprint Review and Sprint Retrospective

At the end of the sprint, the team performs two practices:

Sprint Review

The team demonstrates what they have accomplished to stakeholders. They demo the software and show its value.

Sprint Retrospective

The team takes time to reflect on what went well and which areas need improvement. The outcomes from the retrospective are actions for the next sprint.

Increment

The product of a Sprint is called the “Increment” or “Potentially Shippable Increment”. Regardless of the term, a sprint’s output should be of shippable quality, even if it’s part of something bigger and can’t ship by itself. It should meet all the quality criteria set by the team and Product Owner.

Repeat, Learn, and Improve

The entire cycle is repeated for the next sprint. Sprint Planning selects the next items on the Product Backlog, and the cycle repeats. While the team is executing the sprint, the Product Owner is ensuring the items at the top of the backlog are ready to execute in the following sprint.

This shorter, iterative cycle provides the team with lots of opportunities to learn and improve. A traditional project often has a long lifecycle, say 6-12 months. While a team can learn from a traditional project, the opportunities are far less than a team who executes in 2-week sprints, for example.

This iterative cycle is, in many ways, the essence of Agile.

Scrum is very popular because it provides just enough framework to guide teams while giving them flexibility in how they execute. Its concepts are simple and easy to learn. Teams can get started quickly and learn as they go. All of this makes Scrum a great choice for teams just starting to implement Agile principles.

Secure Coding Guideline

Mon, 01 Jan 0001 00:00:00 +0000

Secure coding standards are guidelines, best practices, and coding conventions that can be used by software developers to prevent security vulnerabilities and improve the overall quality of the software during the software design & development phases.

The guidelines are intended as a reference and best practice guidelines complement static code analysis tools like Klocwork or Sonarqube. It can help address code smells and design vulnerabilities which are usually missed during static code analysis. It also ensures adherence to best practices and commonly accepted security standards.

This wiki lists the secure coding guidelines followed within ABB. It also provides references to official and generic security best practices & software coding guidelines categorized based on programming language stacks.

ABB Secure Coding Guidelines

3BSE084586 Secure Coding Guideline

Programming Language-Specific Coding Guidelines

C

Python style guide Google Style guide-Python

Perl

Security Guidelines

SEI CERT Perl Coding Standard

Android

Security Guidelines

Android Secure coding standard

NodeJS

Security Guidelines

NodeJS Security Guidelines

Docker

Security Guidelines

OWASP Docker security cheat sheet

Cloud

Microsoft Azure Google Cloud AWS

REST

Microsoft REST API Guidelines

Security Best Practices & Guidelines

The below links point to generic security best practice guidelines and recommendations that can be referred to during the software design and development phases.

SonarSource Security Rules Microsoft Secure Development Lifecycle Security Knowledge Framework CWE/SANS TOP 25 Most Dangerous Software Errors CWE Top 25 Vulnerabilities OWASP Secure Coding Practices - Quick Reference Guide OWASP Cheat Sheets Microsoft CVE Vulnerabilities Google Web Security Guide Google Style guides

Secure Coding Guideline, .NET

Mon, 01 Jan 0001 00:00:00 +0000

This document describes the secure coding guidelines for the .NET programming language. Some of the guidelines are generic, whereas some are specific to the .NET programming language.

.Net Framework Guidance

Data Access

Use Parameterized SQL commands for all data access, without exception.
Do not use SqlCommand with a string parameter made up of a concatenated SQL String.
Whitelist allowable values coming from the user. Use enums, TryParse, or lookup values to assure that the data coming from the user is as expected.
- Enums are still vulnerable to unexpected values because .NET only validates a successful cast to the underlying data type, integer by default. Enum.IsDefined can validate whether the input value is valid within the list of defined constants.
Apply the principle of least privilege when setting up the Database User in your database of choice. The database user should only be able to access items that make sense for the use case.
The use of the Entity Framework is a very effective SQL injection prevention mechanism. Remember that building your own ad hoc queries in EF is just as susceptible to SQLi as a plain SQL query.
When using SQL Server, prefer integrated authentication over SQL authentication.
Use Always Encrypted where possible for sensitive data (SQL Server 2016 and SQL Azure),

Encryption

Never, ever write your own encryption.
Use the Windows Data Protection API (DPAPI) for secure local storage of sensitive data.
Use a strong hash algorithm.
- In .NET (both Framework and Core), the strongest hashing algorithm for general hashing requirements is System.Security.Cryptography.SHA512.
- In the .NET framework, the strongest algorithm for password hashing is PBKDF2, implemented as System.Security.Cryptography.Rfc2898DeriveBytes.
- In .NET Core, the strongest algorithm for password hashing is PBKDF2, implemented as Microsoft.AspNetCore.Cryptography.KeyDerivation.Pbkdf2, which has several significant advantages over Rfc2898DeriveBytes.
- When using a hashing function to hash non-unique inputs such as passwords, use a salt value added to the original value before hashing.
Make sure your application or protocol can easily support a future change in cryptographic algorithms.
Use Nuget to keep all of your packages up to date. Watch the updates on your development setup, and plan updates to your applications accordingly.

General

Lockdown the config file.
- Remove all aspects of configuration that are not in use.
- Encrypt sensitive parts of the web.config using aspnet_regiis -pe
For Click Once applications, the .Net Framework should be upgraded to use version 4.6.2 to ensure TLS 1.1/1.2 support.

Securing State Data

Applications that handle sensitive data or make any kind of security decisions need to keep that data under their own control and cannot allow other potentially malicious code to access the data directly. The best way to protect data in memory is to declare the data as private or internal (with a scope limited to the same assembly) variables. However, even if this data is subject to access you should be aware of:

Using reflection mechanisms, highly trusted code that can reference your object can get and set private members.
Using serialization, highly trusted code can effectively get and set private members if it can access the corresponding data in the serialized form of the object.
Under debugging, this data can be read.

Make sure none of your methods or properties exposes these values unintentionally.

Security and User Input

User data, which is any kind of input (data from a Web request or URL, input to controls of a Microsoft Windows Forms application, and so on), can adversely influence code because often that data is used directly as parameters to call other code. This situation is analogous to malicious code calling your code with strange parameters, and the same precautions should be taken. User input is harder to make safe because there is no stack frame to trace the presence of potentially untrusted data.

These are among the subtlest and hardest security bugs to find because, although they can exist in code that is seemingly unrelated to security, they are a gateway to pass bad data through to other code. To look for these bugs, follow any kind of input data, imagine what the range of possible values might be, and consider whether the code seeing this data can handle all those cases. You can fix these bugs through range checking and rejecting any input the code cannot handle.

Some important considerations involving user data include the following:

Any user data in a server response runs in the context of the server’s site on the client. If your Web server takes user data and inserts it into the returned Web page, it might, for example, include a <script> tag and run as if from the server.
Remember that the client can request any URL.
Consider tricky or invalid paths:
- ..\, extremely long paths.
- Use of wild card characters (*).
- Token expansion (%token%).
- Strange forms of paths with special meaning.
- Alternate file system stream names such as filename::$DATA.
- Short versions of file names such as longfi~1 for longfilename.
Remember that Eval(userdata) can do anything.
Be wary of late binding to a name that includes some user data.
If you are dealing with Web data, consider the various forms of escapes that are permissible, including:
- Hexadecimal escapes (%nn).
- Unicode escapes (%nnn).
- Overlong UTF-8 escapes (%nn%nn).
- Double escapes (%nn becomes %mmnn, where %mm is the escape for ‘%’).
Be wary of user names that might have more than one canonical format. For example, you can often use either the MYDOMAIN\username form or the username@mydomain.example.com form.

Security and Race Conditions

Another area of concern is the potential for security holes exploited by race conditions. There are several ways in which this might happen. The subtopics that follow outline some of the major pitfalls that the developer must avoid.

Race Conditions in the Dispose Method

If a class’s Dispose method (for more information, see Garbage Collection) is not synchronized, the cleanup code inside Dispose can be run more than once, as shown in the following example.

void Dispose()
{
 if (myObj != null)
 {
 Cleanup(myObj);
 myObj = null;
 }
}

Because this Dispose implementation is not synchronized, it is possible for Cleanup to be called by the first thread and then a second thread before _myObj is set to null. Whether this is a security concern depends on what happens when the Cleanup code runs.

A major issue with unsynchronized Dispose implementations involves the use of resource handles such as files. Improper disposal can cause the wrong handle to be used, which often leads to security vulnerabilities.

Race Conditions in Constructors

In some applications, it might be possible for other threads to access class members before their class constructors have completely run. You should review all class constructors to make sure that there are no security issues if this should happen or synchronize threads if necessary.

Race Conditions with Cached Objects

Code that caches security information or uses the code access security Assert operation might also be vulnerable to race conditions if other parts of the class are not appropriately synchronized, as shown in the following example.

void SomeSecureFunction()
{
 if (SomeDemandPasses())
 {
 fCallersOk = true;
 DoOtherWork();
 fCallersOk = false;
 }
}
void DoOtherWork()
{
 if (fCallersOK)
 {
 DoSomethingTrusted();
 }
 else
 {
 DemandSomething();
 DoSomethingTrusted();
 }
}

If there are other paths to DoOtherWork that can be called from another thread with the same object, an untrusted caller can slip past a demand.

If your code caches security information, make sure that you review it for this vulnerability.

Race Conditions in Finalizers

Race conditions can also occur in an object that references a static or unmanaged resource that it then frees in its finalizer. If multiple objects share a resource that is manipulated in a class’s finalizer, the objects must synchronize all access to that resource.

Security and On-the-Fly Code Generation

Some libraries operate by generating code and running it to perform some operations for the caller. The basic problem is generating code on behalf of lesser-trust code and running it at a higher trust. The problem worsens when the caller can influence code generation, so you must ensure that only code you consider safe is generated.

You need to know exactly what code you are generating at all times. This means that you must have strict controls on any values that you get from a user, be they quote-enclosed strings (which should be escaped so they cannot include unexpected code elements), identifiers (which should be checked to verify that they are valid identifiers), or anything else. Identifiers can be dangerous because a compiled assembly can be modified so that its identifiers contain strange characters, which will probably break it (although this is rarely a security vulnerability).

It is recommended that you generate code with reflection emit, which often helps you avoid many of these problems.

When you compile the code, consider whether there is some way a malicious program could modify it. Is there a small window of time during which malicious code can change source code on disk before the compiler reads it or before your code loads the .dll file? If so, you must protect the directory containing these files, using an Access Control List in the file system, as appropriate.

Role-Based Security

Roles are often used in financial or business applications to enforce a policy. For example, an application might impose limits on the size of the transaction being processed depending on whether the user making the request is a member of a specified role. Clerks might have the authorization to process transactions that are less than a specified threshold, supervisors might have a higher limit, and vice presidents might have a still higher limit (or no limit at all). Role-based security can also be used when an application requires multiple approvals to complete an action. Such a case might be a purchasing system in which an employee can generate a purchase request, but only a purchasing agent can convert that request into a purchase order that can be sent to a supplier.

.NET Framework role-based security supports authorization by making information about the principal, which is constructed from an associated identity, available to the current thread. The identity (and the principal it helps to define) can be either based on a Windows account or be a custom identity unrelated to a Windows account. .NET Framework applications can make authorization decisions based on the principal’s identity or role membership or both. A role is a named set of principals that have the same security privileges (such as a teller or a manager). A principal can be a member of one or more roles. Therefore, applications can use role membership to determine whether a principal is authorized to perform the requested action.

To provide ease of use and consistency with code access security, the .NET Framework role-based security provides System.Security.Permissions.PrincipalPermission objects that enable the common language runtime to perform authorization in a way that is similar to code access security checks. The PrincipalPermission class represents the identity or role that the principal must match and is compatible with both declarative and imperative security checks. You can also access a principal’s identity information directly and perform role and identity checks in your code when needed.

The .NET Framework provides role-based security support that is flexible and extensible enough to meet the needs of a wide spectrum of applications. You can choose to interoperate with existing authentication infrastructures, such as COM+ 1.0 Services, or to create a custom authentication system. Role-based security is particularly well-suited for use in ASP.NET Web applications, which are processed primarily on the server. However, .NET Framework role-based security can be used on either the client or the server.

Securing resource access

When designing and writing your code, you need to protect and limit the access that code has to resources, especially when using or invoking code of unknown origin. So, keep in mind the following techniques to ensure your code is secure:

Do not use Code Access Security (CAS).
Do not use partially trusted code.
Do not use the AllowPartiallyTrustedCaller attribute (APTCA).
Do not use .NET Remoting.
Do not use Distributed Component Object Model (DCOM).
Do not use binary formatters.

Code Access Security and Security-Transparent Code are not supported as a security boundary with partially trusted code. We advise against loading and executing code of unknown origins without putting alternative security measures in place. The alternative security measures are:

Virtualization
AppContainers
Operating System (OS) users and permissions
Hyper-V containers

External References

Secure Coding Guideline, C

Mon, 01 Jan 0001 00:00:00 +0000

This document describes the secure coding guidelines for the C programming language. Some of the guidelines are generic, whereas some of them are specific to the C programming language.

Code Priority Classification

Courtesy: Microsoft SDL documentation.

The source code being developed or reviewed should be classified as below.

Code Priority	Description
Priority 1	All Internet or network-facing code. Code in the Trusted Computing Base (TCB) (for example, code executing in kernel mode). Code running under root account. Code running as an elevated user Any code that handles secret data, such as encryption keys and passwords. All code-supporting functionality is exposed on the maximum attack surface
Priority 2	Code that runs under a non-root account
Priority 3	Test scripts, automation scripts

Security Bugs

Security Bug Bar

Courtesy: Microsoft SDL documentation here

Classification

Description

Critical

Elevation of privilege: The ability to either execute arbitrary code or obtain more privilege than authorized.

Remote anonymous users.

Examples:

Unauthorized file system access: arbitrary writing to the file system
Execution of arbitrary code
SQL injection (that allows code execution)
All write access violations (AV), exploitable read AVs, or integer overflows in remote anonymously callable code

High

Code that runs under a non-root account

Priority 3

Test scripts, automation scripts

Security Bug classification

Generic

C secure coding guidelines

Introduction

C has been intensely criticized as an insecure programming language. Despite the many vulnerabilities attributed to buffer overflows and point manipulation, secure code can still be developed with C.

This document summarizes the common guidelines for C. Further details and other guidelines are available in the CERT C Secure Coding Standard. In addition to this document, you should utilize Klocwork (a static analyzer for which ABB has an enterprise license) to analyze your code. Review the general coding guidelines for aspects such as input validation and resource management.

Avoid Unsafe Methods

Avoid using unsafe methods such as gets(), strcat(), and strcpy(). These methods do not check boundaries when copying data to the destination. As such, it becomes possible to insert arbitrary code into the system.

Header Files

Use parenthesis within macros around parameter names

When defining macros, parenthesis should surround any parameters, except in a list separated by commas. This prevents issues with unexpected operator precedence when such macros are expanded. (CERT C, PRE-01-C)

Macros should not end with a semi-colon

When a macro ends with a semi-colon, it can lead to an empty statement being produced for the output, affecting the intended output. (CERT C, PRE-11-C)

Declarations and Initialization

Variable Arguments

When feasible, avoid the use of variable argument functions. If such functions are necessary, ensure the “contract” between caller and callee is maintained. (CERT C, DCL-10,11)

Declare Zero Parameters Functions with Void

For functions that do not take any parameters, declare these with a “void” parameter. This will force compiler warnings if such a function is called with parameters. (CERT C, DCL-20)

Expressions

Parenthesis

Use parentheses to ensure proper precedence with operations. (CERT C, EXP00-C)

Type Sizes

Do not use the size of a pointer to assume that it is the same size as the associated type. Do not assume the size of a structure is the sum of the size of the members. (CERT C, EXP01-C, EXP-03C)

Pointer Arithmetic

Ensure pointer arithmetic is used properly. Otherwise, the wrong memory address is referenced. (CERT C, EXP-08-C)

Integers

Define Integer Constants Safely

Integer constants are often used to specify bit-masks and other boundary checks. As the size of integers can vary across platforms, constants should be specified in a platform-independent manner. (CERT C, INT-17-C)

Floating Point

Understand Floating Point Limitations

Floating-point numbers have finite precision and are prone to errors with rounding. If exact values are needed, then another type should be selected. Additionally, no guarantees on the underlying specifics of the floating-point system exist, so no assumptions should be made on the precision and/or range. (CERT C, FLP-00-C)

Arrays

Do not use the `sizeof` operator to the array pointer

This returns the size of the pointer itself rather than the data structure it references. (CERT C, ARR-01-C)

Check Array Boundaries

Ensure that you only access legitimate portions of the array. Array indexing starts at zero. This is especially critical when expressions are used to index the array.

Strings

A multitude of security issues has arisen from C’s poor implementation of strings. Issues exist among the representation, management, and manipulation of C-style strings. For representation, the strings are null-terminated. Thus it is necessary to scan the entire string to find the length or last location.

While strings can also be managed by using standard, well-proven functions of malloc(), free(), strlen(), memcpy(), and snprintf(), these functions can be difficult to use correctly in practice and have poor abstractions compared to languages such as Java and C#. The edge security team relies on CSA safe string functions. E.g., CSA_StrLen should be used instead of strlen, and OSA_snprintf should be used instead of sprintf.

Check String Bounds

When implementing strings, use functions that check the string boundaries to overflow issues.

Memory

Memory management is one of the more difficult tasks to correctly implement within C programs. Any time memory is allocated, you must ensure the memory is deallocated when no longer required. Consider using a library to track your memory usage while the application executes. Once the memory is allocated, you will need to initialize it. Once you have freed memory, you should no longer access it.

Input / Output

All open files should be closed when no longer in use. Ensure when opening files specified by a user that the name is valid and isn’t being referenced to a location that should not otherwise be accessed. E.g., using “..” to move up the directory structure to a new file location. When creating an output format string, ensure that it is properly formatted – especially if such a string originated from the user.

Environment

Avoid System()

Where possible, avoid the use of the system() to call executable programs. Either user existing C functions if possible or exec(). (CERT-C ENV04-C)

Signals

Avoid using signals to implement normal functionality or flow of control. Ensure code accessed within signal handlers is thread-safe, does not access shared memory, and is asynchronous-safe. Many common standard libraries such as free() and fprintf() are not appropriate to use within signal handlers. (CERT-C SIG00-C, CERT-CSIG30-C)

Error Handling:

Return values from all functions should be checked, with the error handling functionality implemented correctly.

Link to common return values: https://wiki.sei.cmu.edu/confluence/display/c/ERR33-C.+Detect+and+handle+standard+library+errors. (CERT-C, ERR33-C)

Concurrency

Applications often have multiple threads of control. Care must be taken to ensure shared resources such as memory are appropriately protected by synchronization mechanisms to ensure the application stays within a consistent state.

Wikipedia https://en.wikipedia.org/wiki/Synchronization_(computer_science) presents several of the common synchronization methods. These methods are often unique to a particular operating system, although the POSIX Thread library has been established as a standard. A good overview of threads is available at https://hpc-tutorials.llnl.gov/posix/.

Secure Coding Guideline, ReactJS

Mon, 01 Jan 0001 00:00:00 +0000

This document describes the secure coding guidelines for ReactJS. Some of the guidelines are generic, whereas others are specific to ReactJS.

ReactJS Framework Guidance

Input validation – It should handle validations on the presentation and application layers for user inputs to prevent injection attacks rather than implementing complex custom validations.

Ex - Validating e-mail addresses using the Validator.js library
```
 var validator = require('validator');

 var isValidEmail = validator.isEmail('foo@bar.com');
```

Output encoding — Data passing from the backend to the UI should be encoded or sanitized properly from malicious payloads. If it’s not encoded properly, potential security threats should occur while loading the UI.

While rendering the user name on UI, the hacker will execute and inject the script. So, to prevent this, a proper encoding library should be used.

Example – using the node-esapi library

Encoding output in the context of HTML:

 var esapi = require('node-esapi');

 var esapiEncoder = esapi.encoder();

 var htmlOutput = esapiEncoder.encodeForHTML('<div> User Name <script type="javascript"> alert("Your site hacked!") </script> </div>');

The result of htmlOutput will be encoded appropriately to escape the malicious script tags:

 &lt;div&gt; User Name &#x21; &lt;script type&#x3d;&quot;javascript&quot;&gt; alert&#x28;&quot; Your site hacked &#x21;&quot;&#

Regular Expressions – if some common regular expressions aren’t properly written, they can degrade CPU performance and raise performance issues in your applications.

Example:

 var re = /^((abc)*)+$/;

 console.log(re.exec('abcabcabcabcabcabcabcabcabcabcabcabcabcabcabcabcabcabcabcabcabcabcabcabcabcabcabcabcabcabca'));

After running this in the local development machine, it took approximately 40 seconds, as can be seen:

 $ time node re.js
 null

 node re.js  41.88s user 0.00s system 99% cpu 41.883 total

So to avoid this, some Safe Regular Expression libraries can be used like Safe – Regex

 var saferegex = require('safe-regex');

 var emailRegex = /^([a-zA-Z0-9])(([\-.]|[_]+)?([a-zA-Z0-9]+))*(@){1}[a-z0-9]+[.]{1}(([a-z]{2,3})|([a-z]{2,3}[.]{1}[a-z]{2,3}))$/;

 console.log(saferegex(emailRegex));

JavaScript’s Strict Mode - Strict mode was introduced in ECMAScript 5.1 to enable a restricted version of JavaScript for enhanced security and error management.

If a strict mode has been followed, then compilation time will enforce its rules.

Example:
```
 if(‘100’ == 100) { } // condition will be true without strict mode
 if(‘100’ === 100) { } // condition will be false in strict mode
```
Cryptography Practices - cryptographic functions like MD5 and SHA can be used to prevent server breaches or data leakage through SQL Injection or other attacks.

Preventing XSS attacks

Always sanitize the users’ content that comes from forms.

Always prefer to serialize instead of JSON.stringify.

Use dangerouslySetInnerHTML only when absolutely necessary.
Do unit tests for all your components, and try to cover all the possible XSS attacks that some users could do.
Always encrypt the passwords with sha1 and md5 (together), and also add a salt value (for example, if the password is abc123, then your salt can be encrypted like this: sha1(md5('$4lT3xt_abc123')).
If you use cookies to store sensitive information (personal information and passwords mainly), you can save the cookie with Base64 to obfuscate the data.
Protect your APIs (using security tokens) unless you need a public API.

Software Artifact Model

Mon, 01 Jan 0001 00:00:00 +0000

The software artifact model describes the relationship between artifacts used in software development.

The picture below visualizes the software artifact model.

Figure 1: Software Artifact Model

Component Capability

Component capabilities describe what the corresponding version of a component is capable of in its currently implemented state.

For more details, follow this link: Component Capabilities Guideline

Detailed Design

Detailed Design is based on architecture documentation along with Feature descriptions and acceptance criteria. Part of the design work is a Feature breakdown into User Stories and Tasks. The design is documented in the repository of the source code. This also holds for SDK documentation.

Modeling is done using an approved UML diagrams tool (e.g. PlantUML, Enterprise Architect is used for products that have already been modeled using Enterprise Architect).

Also, Threat modeling is a related but more high-level activity.

Code

Implementation includes the following:

Writing code on short-lived Git branches using the established collection of coding guidelines.
Writing Unit and Component tests (see section further below).

Pull requests

When a task for updating documentation, test cases, or source code has been implemented, a pull request^*) is created and linked to the Task work item.

The completion of the pull request includes the following steps:

Code and documentation review (done as part of the pull request completion)
Execution of Pull request build job which performs:
- Static code analysis
- Execution of automated tests (including regression tests)
- Check on code coverage
- Generation of HTML site using Doxygen
- Build and publication of artifacts to be picked up by a Release pipeline

^*) If using Team Foundation Version Control (TFVC) instead of Git, pull requests correspond to check-ins and branches to shelve requests.

Unit Test cases

A Unit test is usually a box test of a separate class or function to verify its behavior. Automatic tests are developed for all code and executed as part of the pull request before the code is integrated.

Test cases shall be independent of the order of test case execution. Code coverage is measured during execution and compared with the defined minimum acceptable level.

Unit test cases are described (including steps and expected results) together with the test code, or in a Test case work item linked to the test code. How to include the documentation depends on the framework and is included in the framework descriptions.

The test result will be analyzed in the data of the pull request execution (e.g. the pull request will not finish if there are failed tests).

Component Test cases

Component tests shall test the feature and user story acceptance criteria. Component tests are mostly automated and executed in pipeline build jobs.

Similarly to unit tests, component tests are documented together with the test code or in a test-case work item linked to the test code.

The result of the component test execution can be analyzed in the build job output.

Manual test cases are rare in software unit and component tests. In cases they are needed, they should be defined in Test Case work items and be part of a Test suite in Azure DevOps. When the manual test cases are being performed, execution of the Test suite should be triggered so that the test result is registered directly in Azure DevOps.

References

For more detailed guidance about software development, please find the relevant guides at the following link where you can learn more about component capabilities, static code analysis, code review, secure coding, and much more:

Software Guides

SonarQube

Mon, 01 Jan 0001 00:00:00 +0000

SonarQube is a shared static code analysis tool hosted on the ABB LAN network.

Where to find the tool

SonarQube as a web-based tool is hosted in a web server available under the following link - https://xc-s-zw00510.xc.abb.com/projects.

There is also a client-side tool designated for Visual Studio and Visual Studio Code IDE integration called “Sonar Lint” - which is available under the following link https://www.sonarlint.org.

Description

SonarQube is an open-source platform developed by SonarSource for continuous inspection of code quality to perform automatic reviews with static analysis of code to detect bugs, code smells, and security vulnerabilities in 20+ programming languages. SonarQube offers reports on duplicated code, coding standards, unit tests, code coverage, code complexity, comments, bugs, and security vulnerabilities.

SonarQube can record metrics history and provide evolution graphs. SonarQube provides fully automated analysis and integration with Maven, Ant, Gradle, MSBuild, and continuous integration tools (Azure DevOps, Jenkins, etc.).

SonarQube integrates with Eclipse, Visual Studio, and IntelliJ IDEA development environments through the SonarLint plug-ins, and also integrates with external tools like LDAP, Active Directory, GitHub, and others. SonarQube is expandable with the use of plug-ins.

Motivation

SonarQube identifies all types of issues that may come during the development cycle covering all aspects of security issues, vulnerabilities, and quality defects. SonarQube improves code maintainability in the short and long run.

The cyber security team together with the DevOps team did a tool evaluation which is available in Microsoft Team Share.

How to analyze the code

With proper integration, the tool will inform the developer early during development on the fly, so the developer can see how to correct problems even before preparing a pull request. The second analysis is done during the pull request process, via a mechanism called pull request decoration. This prevents from put on master branch unwanted quality issues.

New and changed code

SonarQube is presenting information about new and changed code which is going to be put on the master branch - this is called “new code”, and is blocked on pull requests until all quality conditions are met. This way developers can distinguish between the existing code base and new changes. Blocking mechanisms ensure the focus of quality practices among the teams.

Existing code base

SonarQube presents information about existing code quality, which is in the form of a web page dashboard. It is organized as a flag that simply informs about two states (passed, failed).

New versions

This is the responsibility of the team administering SonarQube inside ABB.

Rule set

Configuration of the rule set is under the SonarQube administrator’s responsibility.

Official documentation regarding rules in SonarQube can be found under the following links:

Rules User Guide Adding Coding Rules

Storage

All SonarQube rules are stored on the server.

Defined rules for each programming language can be found in the ‘Rules’ tab on the SonarQube web page.

SonarQube Rules in ABB Instance

Version control

This is the responsibility of the team administering SonarQube inside ABB.

Add/remove rules

Configuring the rule set is under the SonarQube administrator’s responsibility.

Official documentation regarding rules in SonarQube can be found under the following links:

Rules User Guide Adding Coding Rules

New rule set from new tool version

The built-in rules get updated when either the version of SonarQube is upgraded or the language-specific extensions are updated. The custom rulesets are updated and managed by teams. SonarQube team normally sends out notifications regarding any planned upgrades. The product page of SonarSource maintains a changelog of all the changes.

SonarQube update is the responsibility of the SonarQube administration team.

Standards

The SonarQube Quality Model has three different types of rules: Reliability (bug), Vulnerability (security), and Maintainability (code smell) rules.

The vast majority of security-related rules originate from established standards: CWE, SANS Top 25, and OWASP Top 10.

Official documentation regarding security rules in SonarQube can be found under the following link:

Security Rules User Guide

Monitoring

Monitoring is done on the SonarQube server, where different dashboards can be used to view different issues, statuses, or severities. A pull request in Azure DevOps shall be set up with a required check that blocks the pull request from completing while there are unhandled SonarQube issues in the code.

Severity levels

This is specific to the tool, severity metrics are set up automatically based on rules defined in the software. Then developer team can change that to reflect real-life situations. (quality issue, false positive).

How to handle deviations

In case of bugs, security hotspots, and vulnerabilities those can be handled with appropriate status: To review, Fixed, Safe.

In case of code smell deviation it can be handled as well with appropriate status: Open, Confirm, Resolve as fixed, Resolve as false positive, Resolve as won’t fix. The overall status of the analysis is updated accordingly.

Deviations in code coverage are “work in progress”.

Materials

Materials and recordings regarding SonarQube are available in the DevOps team in Microsoft Teams.

Standard Bug Templates

Mon, 01 Jan 0001 00:00:00 +0000

This guideline describes the custom standard fields used in bug templates. For a more general picture of the standard work item template change process in Azure DevOps, see ADO standard work item template change management process.

Overview

The bug template is an ABB customized template displaying the minimum requirements of fields including standard state as in the Azure DevOps Agile template plus ABB-specific fields. These specific fields are described below.

The CM process group is responsible for updating the standard bug template that is found in Opex - Repos - Configuration Management. Both templates used on-premises and in the cloud are managed by the group.

List of standard custom fields to add

Effect CVSS CVSS Calculator Regression How Found Product Issue Number (PIN) External Reference Definition of Ready / Definition of Done Scope Bug Cloned Impact Analysis Introduced In

Security fields

To capture any potential impact on security issues, three security fields are added to be filled in case the bug is a security bug:

Effect

The Effect field states the security effect of the bug. Effect is a mandatory field. For more information, see Bug Classification

CVSS

CVSS (Common Vulnerability Scoring System) is a standard used to estimate the severity of system vulnerabilities. Example: 8.3

CVSSCalc

CVSSCalc provides the link https://www.first.org/cvss/calculator/ to the CVSS standard web page where CVSS can be estimated to a numerical value. The calculation vector is stored in this field to show how the CVSS score was calculated.

Example: https://www.first.org/cvss/calculator/4.0#CVSS:4.0/AV:N/AC:L/AT:N/PR:N/UI:N/VC:L/VI:H/VA:N/SC:N/SI:H/SA:N/MPR:L/MVC:L/R:A/RE:L/U:Green

Regression

For a definition of regression bugs, see the Regression Bugs guide.

The field named Regression is false by default and is set to True if the bug is a regression bug.

How Found

The How Found field is used to track when a bug was found. This is mandatory to fill in when registering the bug. One of the following items can be selected:

Entry	Bug found
01-Requirements	due to wrong/ambiguity requirement
02-Design	due to wrong design
03-Development	during development/unit testing
04-Deployment	during deployment
05-Dev Test	during manual testing
06-Dev Test Automation	during automatic testing
07-Documentation	during User documentation validation
08-SIT	during System Integration test
09-STT	during System Type test
10-STT Automation	during automatic System Type test
11-Media Verification	during Media verification test
12-Pilot	during pilot phase by LBL/customer
13-Post Release	after release, by customer
14-Forward Port	fixing the bug in a newer version

Product Issue Number (PIN)

Product Issue Number (PIN) is a unique identifier for every problem reported for the product life cycle and it is not changed once assigned. A Product Issue Number shall be the only used identifier for an issue during communication via support cases, Field Communications, etc.

External Reference

External reference is the link between the Bug raised in ADO (L4 bug) and Salesforce (customer) case.

Definition of Ready / Definition of Done

Definition of Ready and Definition of Done is implemented as a custom control using the Appgami checklist extension.

Prerequisite: The Appgami checklist extension is needed and it requires a commercial license for each organization. If the extension is not available, work item type definitions cannot be loaded correctly. If the license expires, data will still be available in work items, and queries will still work, but checklists will not be visualized by the custom control.

DoR is made of 3 fields:

Definition of Ready
DoR Progress
DOR Completion

DoD is made of 3 fields:

Definition of Done
DoD Progress
DOD Completion

Example:

How to find work items where the Definition of Ready is not complete? DoR Completion <> Yes

ScopeBug

Boolean field that represents whether the bug is considered a scope bug or not. It is false for introduced bugs found during internal testing, true for deferred bugs and post release bugs.

See How-to Handle Deferred Bugs and How to Handle Bugs in Multiple Releases.

Cloned

Yes/No field that represents whether the bug is a clone of another one. (Note: It is a Yes/No text field and not boolean due to historical reasons)

Default value: No

The original bug has Cloned=No, the new bug cloned from it has Cloned=Yes.

See How-to Handle Deferred Bugs and How to Handle Bugs in Multiple Releases.

Impact Analysis

Free text field to be used to answer impact analysis questions. The questions can be customized depending on project.

Introduced In

The oldest release where the bug is known, where it was first introcuded. The allowed values are the same as area path. If multiple instances (duplicates) of this bug exist, this field is readonly in the copies and can be written only in the original bug, the one having “Cloned”=No.

Standard Document Update Template

Mon, 01 Jan 0001 00:00:00 +0000

This guideline describes the Document Update work item type and the custom standard fields used in its template. For a more general picture of the standard work item template change process in Azure DevOps, see ADO standard work item template change management process.

Overview

The Document Update work item is an ABB specific work item used to track changes on documents under formal change management e.g project steering document or a product document.

Document Updates can also be used to manage changes to any document stored in the Document Management System to facilitate more controlled handling of documents. The Document Update work item is used for both new documents and for updates in previously approved ones. One work item is used to handle updates in one document. The request to change a document could come from a change in requirement, an impact analysis or updates needed due to errors or modifications in functionality.

The Document Update work item can be used as a task and linked to a user story or bug. If an error is found in a manual or other customer documentation, a bug, and not a document update, should be created.

Review Details

When the document is reviewed and approved, add the names of the reviewers if review type is ‘Minor’, or a reference to full review record if review type is ‘Full’.

Document Data

Document Id

The id of the document as the identifier.

Rep. Doc. Revision

The current revision of the document to be updated. “New”, if it is a new document.

Document Type

The type of the document to be updated. The document type should be the same as in OnePCP DMS.

Changed Doc. Revision

The revision of the document after update.

Review Decisions

Review Type

The type of review needed for the update. Review type is decided by the CCB.

Different types:

Full
Minor - The change is an enhancement or an error correction with minor impact on design, no impact on safety or safety concept, and no consequences for any other components (hardware related) or modules (software related). A minor change is only possible when no new requirement or no change of an existing requirement has to be done. A minor review is sufficient if the previous statements are fulfilled, unless:
- It is more than 2 years since the last approved full review was done
- The document has been approved 3 times without a full review.
Not Applicable

Review Date

Date of the review meeting.

Standard Epic Template

Mon, 01 Jan 0001 00:00:00 +0000

This guideline describes the custom standard fields used in the Epic template. For a more general picture of the standard work item template change process in Azure DevOps, see the ADO standard work item template change management process.

Overview

The Epic template is an ABB customized template displaying the minimum requirements of fields including standard state as in the Azure DevOps Agile template plus ABB specific fields. These specific fields are described below.

The Configuration Management process team is responsible for updating the standard bug template that is found in Opex - Repos - Configuration Management. Both templates used on-premises and in the cloud are available.

List of standard custom fields to add:

Overview Definition of Ready / Definition of Done Security Relevant

Definition of Ready / Definition of Done

Definition of Ready and Definition of Done are implemented as a custom control using the Appgami checklist extension.

DoR is made of 3 fields:

Definition of Ready
DoR Progress
DOR Completion

DoD is made of 3 fields:

Definition of Done
DoD Progress
DOD Completion

Example:

How to find work items where the Definition of Ready is not complete? DoR Completion <> Yes

Security Relevant

Security Relevant is a string field with a picklist (Empty by default/True/False)

Is it likely that work will affect a security-critical component?

See How-to Work with Features and Epics

Standard Feature Template

Mon, 01 Jan 0001 00:00:00 +0000

This guideline describes the custom standard fields used in the Feature template. For a more general picture of the standard work item template change process in Azure DevOps, see the ADO standard work item template change management process.

Overview

The Feature template is an ABB customized template displaying the minimum requirements of fields including standard state as in the Azure DevOps Agile template plus ABB-specific fields. These specific fields are described below.

List of standard custom fields to add:

Overview Definition of Ready / Definition of Done Security Relevant Security Relevant Argument Impact Analysis

Definition of Ready / Definition of Done

Definition of Ready and Definition of Done are implemented as a custom control using the Appgami checklist extension.

DoR is made of 3 fields:

Definition of Ready
DoR Progress
DOR Completion

DoD is made of 3 fields:

Definition of Done
DoD Progress
DOD Completion

Example:

How to find work items where the Definition of Ready is not complete? DoR Completion <> Yes

Security Relevant

Security Relevant is a string field with a picklist (Empty by default/True/False)

Is it likely that work will affect a security-critical component?

See How-to Work with Epics and Features

Security Relevant Argument

If a feature is defined as security-relevant, “Security Relevant Argument” is mandatory. This is a multi-line text field.

See How-to Work with Epics and Features

Impact Analysis

Free text field used to write the impact analysis for development work.

Questions are pre-filled but can be customized depending on the project.

Standard System Epic Template

Mon, 01 Jan 0001 00:00:00 +0000

This guideline describes the custom standard fields used in the System Epic template.

Overview

Requirements (System, Product, or Technology) in DFN are typically Product Managers’ tools to provide functional and non-functional requirements to R&D . Also R&D is entitled to file requirements. R&D Team can translate these requirements further to Epics/Features/User Story etc. System Epic is a custom Work Item which is a replica in Azure DevOps to hold these System Requirement information kept in DFN by Product management .

The System Epic template is an ABB customized template , similar to Epic displaying the minimum requirements of fields including standard state as in the Azure DevOps Agile template plus DFN specific fields. These specific fields are listed below.

DFN Specific Information

Following Field values in System Epic will get Synchronized with the same set of Field values in DFN System Requirement.

SR Description

SR Details

SR ID

SR Status

SR Product Line

SR Category

SR Rank

SR Target Release

SR Change Date

SR Owner

MO Id

Classification

This Field gives indication of what type of Requirement is this System Epic hold. Value Area value - Architecture/Business/Enablers (This may be called Type in some projects on prem due to historical reasons)

For more information on working with System Architecture Epic : see System Architecture Epic.

For a more general picture of the standard work item template change process in Azure DevOps, see ADO standard work item template change management process.

Standard Test Case Template

Mon, 01 Jan 0001 00:00:00 +0000

This guideline describes the custom standard fields used in the Test Case template. For a more general picture of the standard work item template change process in Azure DevOps, see ADO standard work item template change management process.

Overview

The Test Case template is an ABB customized template displaying the minimum requirements of fields including standard state as in the Azure DevOps Agile template plus ABB specific fields. These specific fields are described below.

List of standard custom fields to add:

Review Summary Automation Date Automated By Regression Automation Date Automated By

Some fields are locked as readonly when the Test Case is in state Ready:

Title
Description
Steps
Parameters
Priority
Test Type (if applicable)

Review Summary

Review Summary is a multi line text field.

It is used To track review comments and implementation status. It should have following information like Reviewer, Comment type (Major/Minor), Review Comment, Implementation status.

Automation Date

Datetime field When the test case was automated

Automated By

Itentity field

Person who has automated the test case

Regression

Test Type

Standard User Story Template

Mon, 01 Jan 0001 00:00:00 +0000

This guideline describes the custom standard fields used in the User Story template. For a more general picture of the standard work item template change process in Azure DevOps, see ADO standard work item template change management process.

Overview

The User Story template is an ABB customized template displaying the minimum requirements of fields including standard state as in the Azure DevOps Agile template plus ABB specific fields. These specific fields are described below.

List of standard custom fields to add:

Definition of Ready / Definition of Done

Definition of Ready and Definition of Done are implemented as a custom control using the Appgami checklist extension.

Prerequisite: The Appgami checklist extension is needed and it requires a commercial license for each organization. If the extension is not available, work item type definitions cannot be loaded correctly. If the license expires, data will still be available in work items, queries will still work, but checklists will not be visualized by the custom control.

DoR is made of 3 fields:

Definition of Ready
DoR Progress
DOR Completion

DoD is made of 3 fields:

Definition of Done
DoD Progress
DOD Completion

Example:

How to find work items where Definition of Ready is not complete? DoR Completion <> Yes

Static Code Analysis

Mon, 01 Jan 0001 00:00:00 +0000

Static source code analysis is a method for analyzing the source code without executing it.

ABB’s Security Development Lifecycle Standard requires Static Code Analysis of at least all new and changed code. If a static analysis tool is available for the language then such a tool shall be used. The compiler is also a type of static analyzer; however, it analyzes the code for programming language syntax and semantics while advanced static analysis techniques perform a much deeper analysis of the code to uncover potential run-time defects.

Code on which static code analysis shall be applied

Static code analysis is required for software projects and customized third-party libraries if standard languages such as C/C++, C#, and Java are used. All new and changed code has to be analyzed. When analyzing an existing code base, it is not required to fix all warnings, instead, a baseline can be made. But some findings, e.g. security warnings can be required to handle. After baselining, only the differences have to be handled when changing the code if this is supported by the tool.

When changing or upgrading the tool, new warnings may appear and it has to be decided from case to case how to handle these, depending on the severity of the warnings.

Selection of tools

Static code analysis tools shall be chosen for each applicable product or part of the product, see Static Code Analysis Tools for recommended tools. More than one tool can be used if suitable since different tools can have different findings. It is recommended to choose tools that can be smoothly integrated into the “build environment” on the desktop or build server.

The tool shall to the greatest extent support the applicable standards to reduce the use of checklist items for manual code reviews. The relevant R&D cluster lead and the release owner have the responsibility for choosing the tools. It is recommended to use the latest versions of the tools to utilize new and improved rules. For each project, it shall be decided which version of the tools to be used (the latest or a specific version), but it is the R&D cluster lead together with the release owner that has the final responsibility.

If no tool is available for the language then all security checks have to be done during manual code review.

Selection of rule set

For each applicable product, a rule set shall be chosen. The static code analysis tools will analyze the code based on those rules. It is recommended that the code responsible for a product (e.g. repo gate-keeper in git) chooses the rule set, based on the applicable standards and best practices. If no gatekeeper exists, there can be one or several persons responsible for the rule set.

The relevant release owner has the final responsibility of the decision of the rule set. The selected rules shall be defined and placed under version control. The rule set can be defined in the configuration file for the tool if applicable or in a separate document. For further recommendations and best practices relating to secure coding, see Secure Coding Guideline, where there also are links to programming language-specific coding guidelines.

The rules set needs to fulfill the security requirements and include checks that specifically address security vulnerabilities. Known weaknessess are listed by Mitre.org and their lists are good input to the selection of rules.

CWE Top 25 Most Dangerous Software Weaknesses lists the most common and impactful issues experienced over the previous two calendar years. These weaknesses are dangerous because they are often easy to find and exploit. They can allow adversaries to completely take over a system, steal data, or prevent an application from working.

New rules provided by a tool (e.g. with a new version of the tool) need to be considered continuously. There shall exist evidence of which rule sets have been used for the released code.

Documentation

For each product it should be defined and documented

which tool(s) to use
what rule set(s) to use
how the results will be handled

Each new release can reference this documentation together with any modifications of for example version of the tool, changes in rule set, frequency of running the tool.

Build policy

Developers should run the static code analysis tool and handle warnings before integrating the code.

For an effective static analysis adoption, the static code analysis tool should run periodically on the entire product. The frequency shall be defined by the release owner. It is recommended to run it daily as part of the daily build process.

When using git, this should be a part of the commit rules for the pull request, and the pull request should not be possible to complete before all warnings have been handled.

Policy for handling deviations

For new and changed code, all warnings shall be analyzed and resolved before integrating the code. The number of warnings shall be monitored and controlled. The number of warnings shall decrease over time, i.e. new implementation shall not introduce new warnings.

False positives are reported incorrect warnings; they are not really bugs. The false positives show the weakness of the analyzer, hence this needs to be communicated to the tool vendors so that they can improve the tool.

If the warning is correct, then it has to be triaged if the warning is relevant. Deviations from the rules are acceptable if they are motivated. The motivation shall be put in a comment next to the code that caused the warning, or in the tool depending on the tool. If supported by the tool, these deviations from the rules should be handled before checking in. It is recommended that it is the code responsible for a product that approves deviations during code review.

There shall exist evidence of the deviations that have been done in the released code.

If a rule gives too many false positives to be useful or is not helpful for the code quality, it is recommended to disable the rule. This does not include rules that are mandatory if required by for example standards, e.g. security rules. Otherwise, it can be decided by the code responsible for a product.

Progress monitoring

The project’s progress needs to be monitored by assessing the improvements in the code’s quality. The metrics established in the beginning could be used to compare the code quality improvement since the previous builds. Based on the progress, action items could be defined for further static analysis activity.

The R&D cluster lead and the release owner are responsible for making sure that the status of the warnings is followed up during the project and that suitable actions have been taken.

It is recommended metrics are used to follow up on the status of the static code analysis, e.g. the number of warnings that needs to be addressed. It should also be possible to create a report of the remaining warnings and deviations to ensure everything has been handled, e.g. at the end of increments/iterations and before the release.

References

Secure Coding Guideline Static Code Analysis Tools ABB’s Security Development Lifecycle Standard CWE Top 25 Most Dangerous Software Weaknesses

System Requirement Review Guideline

Mon, 01 Jan 0001 00:00:00 +0000

A system requirement review intends to improve the quality of the requirements. It applies both to system requirements and technology requirements.

The purpose of the checklist is to support PCP R&D members, typically product owners and release owners, when invited to review system requirements.

System Requirement Review Goals

Eliminate problems and rework at an early stage
Improve product quality
Ensure common understanding between PPM and R&D on what should be developed
Secure the development flow by ensuring that R&D receives well-defined and prioritized requirements to implement and test

System Requirement Review Checklist

Traceability to Market Opportunity
Consistent with Market Opportunity
Wanted functionality and not a technical solution
Clear/Crisp description – not a broad statement
Consistent with other SRs (conflict, overlap)
Performance aspects covered (if relevant)
Reasonable size or possible to split
Possible to understand impact on the different products
Need for exceptions/limitations
Testable or need for verification criteria
Priority

Security

1) required capability security level (SL-C) of the system/product,
2) security context including scope and boundaries in a physical and a logical way, and
3) required security capabilities related to installation, operation, maintenance, and decommissioning.

PPMs directive for writing System Requirements

To understand PPMs way of working, see their directive for writing the system requirement bellow.

Title: Title of the SR, should briefly describe the functionality without pointing to a specific product or product line or version.
Description: More detailed description
Motivation: State the reason for doing this requirement. If there is no associated MO, the business motivation should be put here.
Exceptions: Document any exceptions or limitations to the requirement.
Verification criteria: Describe suggestions/requirements in how the requirement shall be validated, either on system or product level
Market Opportunity: Reference to related Market Opportunity. Life cycle related System Requirements and Technology Requirements might not have MOs if the need for development is not associated with any change in market functionality.
Priority: Priority relative within one MO, 1 – 5, Used if more than one SR is connected to the same market requirement.
Target release: Do not use if not a specific target release is known, leave empty
Product Line: E.g.: 800xA Extensions; Advanced Services; Compact Product Suite; Digital, etc.
Compatibility: Indicate to which category Evolution — Enhancement — New Feature
Requirement type: e.g. Life Cycle Maintenance; Productization & Logistics; Product Function; Performance & Capacity; Security; Safety; Topology and Deployment; System Management

Underlined are mandatory fields, for more details see PPM’s process description: Managing Market Requirements and System Requirements

References

Managing Market Requirements and System Requirements

Test Techniques

Mon, 01 Jan 0001 00:00:00 +0000

This guideline gives a brief description of test techniques used at the different test levels. A description of the test levels and when to use the various test techniques are defined in each project. The purpose of this document is not to describe all test techniques, but to describe the techniques that have been decided to be appropriate to use in development projects at ABB.

The intended readers of the guideline are developers and testers who design test cases at different levels in order to verify functionality and requirements.

The goal

The goal of testing is to detect as many faults as possible and to demonstrate that the product works according to the specification. Since it is impossible to test all different inputs (exhaustive testing), test strategies and techniques are used to make the testing efficient. This document describes some commonly used techniques.

Despite what test techniques are used both positive and negative tests are needed. Positive tests demonstrate the normal / specified behavior of the system. Negative tests run the system with different input conditions to check whether the system can handle unlikely conditions of the application. In order to efficiently design test cases that verify positive, negative, and unspecified conditions, black-box and white-box testing techniques are used. Black-box techniques are used at all levels of testing, while white-box testing is mostly conducted on the lower levels.

Black-box testing

Black-box testing is a test strategy that investigates the input-output conditions of a program without considering the internal structure. The purpose is to test against a specification (requirements and design) and no insight into or knowledge about the implementation is needed. Hence, the tester does not examine the programming code and does not need any further knowledge of the program other than its specifications. Since only the specification is needed, test cases can be designed as soon as the specifications are complete.

Using the black-box techniques will achieve good coverage of the implemented functionality since all normal execution paths are covered. However, error sequences, recovery situations, and timing/performance issues are difficult to catch with these techniques and should be tested by other techniques. The purpose of the black-box techniques described in this section is to detect functional faults.

Equivalence class partitioning (testing)

An equivalence class is a set of data for which the software’s behavior is assumed to be the same. Thus the result of testing a single value from an equivalence partition is considered representative of the complete partition. This technique reduces the number of different values, for which test cases should be created.

When testing a function (method in a class), equivalence class testing uses the associated parameters (attributes for a method in a class). Each parameter is analyzed and all equivalence classes are determined. An example of equivalence class partitioning is described in Appendix A.

Boundary value analysis

Boundary value analysis can be considered a special case of equivalence class partitioning, since it concentrates the selection of test cases on and around the partition class limits, realizing that many problems can be found when testing on and around limits. Typically also, for boundary value analysis, is to test something with zero as input, max integer value, counters overflow, and testing when something gets full (e.g. the heap) or empty, etc.

An example of boundary value analysis is described in Appendix A.

Interface testing

Testing is conducted to evaluate whether systems or components pass data and control correctly to one another. Faults found during interface testing can be:

Interface misuse – a calling component calls another component and makes an error in its use of its interface, e.g. parameters in the wrong order.
Interface misunderstanding – a calling component embeds assumptions about the behavior of the called component which are incorrect.
Timing errors – the calling and called components operate at different speeds and out-of-date information is accessed.

Interface testing is often conducted by using equivalence class partitioning or boundary value analysis.

Dynamic testing of sequence diagrams

A sequence diagram describes how groups of objects collaborate in accomplishing some system behavior. This collaboration is implemented as a series of messages between objects. Typically, a sequence diagram describes the detailed implementation of a single use case (or one variation of a single use case). Sequence diagrams are not useful for showing the behavior within an object. Test of sequence diagrams is often a part of functional testing.

Testing of sequence diagrams is performed by stimulating the program with the start value of the sequence diagram and then checking whether the program’s correct flow is made in the program. The sequence diagram itself defines input, correct flow, and expected output (end state). At the design test level, the code is either stepped through manually, run through automatically with printouts for each passed operation, or automatically checked in the test program.

State-transition diagrams

State-transition diagrams describe all of the states that an object can have, the events under which an object changes states (transitions), the conditions that must be fulfilled before the transition will occur (guards), and the activities undertaken during the life of an object (actions). State-transition diagrams are very useful for describing the behavior of individual objects over the full set of use cases that affect those objects. State-transition diagrams are not useful for describing the collaboration between objects that cause the transitions.

It is important to test the transitions and not the states described in the diagram to get a full understanding of the functionality. The different states are the expected output of the test cases for the transitions. To show that the different transitions and states have been tested, either the test program automatically has to check it or printouts should be added to the test code.

An example of state-transition diagrams testing is described in Appendix B.

Error guessing

The purpose of error guessing is to use the experience and intuition of a tester to detect faults. The idea is to make educated guesses on which areas are most error-prone and what types of faults are injected in these areas. A procedure for error guessing cannot be given and the best way to explain the concept is to present an example:

When testing a sorting subroutine, the following are situations to explore:

The input list is empty
The input list contains one entry
All entries in the input list have the same value
The input list is already sorted

Thus, by using the experience of a tester the special cases that might have been overlooked are enumerated. Then, the test case design is carried out to expose the possible faults.

Working with error guessing, earlier experiences from the system, and knowledge about commonly made faults are very valuable inputs.

White-box testing

White-box testing (equal to structure-based testing) is a test strategy that investigates the internal structure of a program. The purpose is to design test cases that verify that all the code has been executed, and is correct. Hence, white-box testing does not guarantee that the complete specification has been implemented. In order to conduct white-box testing, a coverage criterion needs to be defined. The coverage criterion defines what is meant by “all code has been executed”.

Workflow

There are two main ways to work with white-box methods and coverage analysis. If test cases have been derived, these can be used as input. Then the coverage of the code is checked. If not full coverage is fulfilled, a decision has to be taken in order to reach full coverage. The test execution with coverage analysis is preferably done with a tool that pre-processes the code.

Coverage methods

In order to know whether full coverage has been achieved, a coverage measure has to be defined. There are several different coverage measures. In this document, only the most commonly used are described. The following program example is used for all coverage measures:

if A>10 and B>10 then
 D:=20;
end;

Statement coverage is defined as every statement in a program that has been executed once. This is the weakest coverage requirement and it does not consider, for example, simple if-statements, logical operators, and loop termination decisions.

An example of a test case for the program example is: a) A=11, B=11 => all statements have been executed

Branch (decision) coverage is defined as every decision in a program that has taken all possible outcomes at least once. A decision is a boolean operand that controls the flow of the program, for example, in an if or while statement. One example of decision coverage is shown below. In this case, the program should be exercised with test cases that cause the if-statement to be both true and false.

Examples of test cases for the program example are:

a) A=11, B=11 => if-statement is true
b) A=0, B=11 => if-statement is false

Hence, the program has taken both decisions in the if-statements.

An example of branch coverage is described in Appendix C.

Condition coverage is defined as every condition in a program that has been both true and false at least once. A condition is a boolean operand in a statement, for example, in an if or while statement.

Examples of test cases for the program example are:

a) A=11, B=0 => Condition (A>10) is true and (B>10) is false
b) A=0, B=11 => Condition (A>10) is false and (B>10) is true

Hence, the program has been exercised with test cases that cause the conditions in the if-statement to be both true and false.

Condition/Decision coverage is defined as every condition in a decision in a program and every decision in the program has taken all possible outcomes at least once.

Examples of test cases for the program example are:

a) A=11, B=11 => Condition (A>10) is true, (B>10) is true, if-statement is true
b) A=0, B=0 => Condition (A>10) is false, (B>10) is false, if-statement is false

Hence, the program has been exercised with test cases that cause the conditions in the if-statement to be both true and false, and the program has taken both decisions in the if-statement.

Modified condition/decision coverage (MCDC) is defined as every condition in a decision that has taken all possible outcomes at least once, and each condition has been shown to affect that decision outcome independently. A condition is shown to affect a decision’s outcome independently by varying just that decision while holding fixed all other possible conditions.

Examples of test cases are:

a) A=11, B=11 => if-statement is true
b) A=0, B=11 => if-statement is false, condition (A>10) affects the outcome
c) A=11, B=0 => if-statement is false, condition (B>10) affects the outcome

Hence, the program has taken both decisions in the if-statement and this has been done by independently varying the conditions. An example of MCDC is described in Appendix C.

Tool Support

Mon, 01 Jan 0001 00:00:00 +0000

This page contains support contacts for commonly used DevOps tools. Although the Configuration Manager (CM) often plays a major role to integrate these tools in pipelines, the CM is not responsible to support in case of issues with the tool, like tool bugs, upgrades, service unavailability. In most cases, these tools are managed and supported by IS. IS will take care of tickets in ServiceNow and will open requests to the vendor if required.

Tool	Support Contact	Resources
Azure DevOps Server and Services	https://abb.service-now.com/_myservices?id=is Common ticket types: General Request - Azure DevOps Global, User Access Management - Azure DevOps Global	Teams: Development Community (Azure DevOps , SonarQube , Tasktop , TFS , ALM)
Black Duck Hub (Synopsys Detect)	sanjeev.s@in.abb.com	https://abb.sharepoint.com/sites/SDIP/Portal/SitePages/OCC.aspx https://abb.sharepoint.com/sites/SDIP/Portal/SitePages/Synopsys%20Detect%20-%20Scanning%20Tool.aspx
SonarQube	https://abb.service-now.com/_myservices?id=is Ticket type: Multipurpose Request to SonarQube - ABB SonarQube Global	https://codescan.abb.com/ Teams: SonarQube channel
Metadefender	https://abb.service-now.com/_myservices?id=is Common ticket types: Submit False Positives Detected by MetaDefender Multiscanning, Add or Remove Access to MetaDefender Multiscanning	Knowledge base

Unit Test Overview

Mon, 01 Jan 0001 00:00:00 +0000

This guide is a quick overview of what a unit test is and when and how it should be used.

What is and general definitions

A unit test is a code validating that any other code (under test) is working as expected.

Validation should ensure the following things:

Code executes successfully when correct data is passed.
Throw proper error messages when incorrect data is passed.

A Unit test:

Runs in memory
Is fully automated
Has full control of everything that it does
A Unit test verifies individual software components or methods, also known as a “unit of work” or “unit of code”.
A unit of code is the smallest piece of code that can be tested.
Unit Testing is a practice in software development for validating that a unit of code will behave as intended and the tested code will produce the same result every time the test is executed.
A Unit test is usually a white box test of a separate class or function to verify its behavior.
A unit test should only test the functionality of a single method, also called method under test or system under test (SUT).
The “System under test” refers to the code that you’re writing unit tests against, this could be an object, service, or anything else that exposes testable functionality.
Code coverage is a measurement of the amount of code that is run by unit tests - either lines, branches, or methods.

The goal

Isolate each part of a program (even a very complex one) and demonstrate that the individual parts are correct and requirements are satisfied.

The ultimate goal is minimizing bugs and allowing developers to focus on the functionalities and logic of the product relying on the fact that individual pieces of code are “correct”.

When and How

Unit test cases are described (including steps and expected results) together with the test code, or in a Test case Work Item linked to the test code.

Unit tests should only test code within the developer’s control. They do not test infrastructure concerns. (Infrastructure concerns include interacting with databases, file systems, and network resources).

How to include the documentation depends on the framework and is included in the framework descriptions.

Test cases shall be independent of the order of test case execution. Code coverage is measured during execution and compared with the defined minimum acceptable level which should be 80%.

All tests will be run continually to the code change requests (pull request in Git, “check-in” in TFS, and so on)

The test result will be analyzed in the data of the pull request execution (e.g. the pull request will not finish if there are failed tests).

All class interfaces will also be tested by exploring the boundary values of each parameter.

General Characteristics

First Class Citizens (Unit test code should be treated as good as your production code, like first-class citizens).
Unit test code should be clean, readable, and maintainable.
No code logic in unit tests (no if, else or for, foreach, while loops)
Isolated - one unit test should not call another unit test method.
Not too specific or general - try to cover all scenarios like passing null, empty collection, and filled collection according to the characteristics of the system under test

References

Unit Test Writing Guideline

Mon, 01 Jan 0001 00:00:00 +0000

In writing a unit test we should keep in mind the following four characteristics (acronym RTFM):

Readable
Trustworthy
Fast
Maintainable

All of these characteristics are equally important and none can be removed without jeopardizing the result.

Readable

Tests should be easy to locate (file structure, how to find a test for a class or method).
Tests should be self-contained, like a little story. Write simple code: do this, call that, assert this.
Test one thing only.
Avoid magic values.
Care a lot about naming your variables (examples…).
Do not prefix with the test if not required by your framework.
Method names for the test (are the only ones where we should not care about the length):
- you will never have to type them a second-time
- use underscore (if not forbidden by your coding guideline) rather than camelCase, it is easier to read when names get long
Naming the test is not that hard, it requires three things:
- the thing that is tested.
- scenario, state under test.
- expected behavior/return value.
Where to put this information is dependent on the framework, usually, the method name is good enough.
If it is the same test, but with different parameters, just add an index.

Trustworthy

Never accept a failing test
Never accept a sporadically failing test
Code coverage is worthless without test-code review
Avoid any logic in test code
Avoid any logic in asserts (more often than anticipated this is copy+paste business logic)
Stupid, readable code. Hardcoded values (especially in asserts).
Never use resources that keep changing (time, random, threads, etc. ).
A good strategy during peer review: introduce a bug in the code and run the unit test, expect it to fail

Fast

That is kind of obvious, but an important property nonetheless to get fast turnaround times during development.

A slow unit test is unlikely to be called frequently, but it should!

Maintainable

Starting from the public interface, they usually start some use cases in the system
Testing private API makes the test brittle, also there needs to be a public method that eventually calls a private method anyway
There shall be no dependency between tests, each test needs to be fully consistent, running alone/altogether/any -order. if there is common work for multiple tests:
- Create objects using common methods (factory, make_XX())
- Manipulate objects / initial state using common methods (init_XX())
- Run Common tests in common methods (verify_XX())
Separation:
- a single thing per test:
  - only one mock object per test (but you can have stub objects just for faking, not asserting)
  - test are hard to name/describe when not separated
  - multiple asserts are a code smell, especially if they are on different objects
- Each test should fail individually (do not early exit as soon as one test fails, you always want to get the full picture. Other tests may pass and give a hint on the nature of the problem) will likely lead to more debugging if tests are not separated

Welcome to QMS-ELSP | ELSP QMS Software

Protection of Development Environment

Purpose

ABB Cyber Security requirements this guide coveres:

Best practices

Example evidence for compliance with ISA/IEC 62443-4-1 and ABB SDLC

Usage of tools

Usage of policies

Minimum needed by development teams

References

Scope

Process Tailoring

Why do Process Tailoring?

What is in Scope for Process Tailoring

Roles involved in Process Tailoring

Where to document the Process Tailoring

Terms and Definitions

Threat Model Periodic Review

1. Purpose

2. Responsibilities of Development Team

3. Periodic Threat Model Review

3.1. Review Existing Threat Model

3.2. Document and Communicate Update

3.3. Plan for Continuous Improvement

4. References

Applicability

Cyber Security User Manual Template

Architecture Review Guideline

Architecture Review Goals

Architecture Review Checklist

Template

How to change the process

Intended for

Activities

Create PCR

Fill in PCR

Submit PCR

PCR evaluation

QMS website updates

Review and Release

Procedure

Guide & Tools

Review

Approval

References

Area and Iteration Path

Area path

Iteration path

Team configuration

Defining backlog levels

MP028

Version: 1.0

Release: 2026-02-11

Summary

Agile Team

Process Overview

Principles

Activities

Artifacts

Details

Master Processes

Cadence view

Flow view

Related references

How-to Change Standard Work Item Templates

Intended for

Activities

Register a process change request

Review the change request

Update the template

Document and share

Details

Why templates are needed

Where to find current templates

References

Guides

Ver: 1.0.1 Rel: 2026-02-12

Summary

Changed

Added