Architecture lifecycle

Introduction

The software architecture work is the result of a collaborative effort involving several team members with different specialties. CompliancePal recognizes this and provides a set of tools to help technical and non-technical contributors manage the architecture lifecycle of a project, from the initial design to the final implementation.

Change management process

In accordance with the design control principles, the software architecture can be modified only via a change management process. The change management process can be implemented with or without a git version control, depending on the project requirements.

With internal backend

The change management process is implemented with an internal backend that is used to store the software architecture specification. The internal backend is used when the project does not use an external version control system, such as git.

Transition	CompliancePal	Description
create	edit architecture	A new draft is created when saving.
edit	edit draft	The draft is edited.
approve	approve draft	The draft is merged.

With Git backend

The change management process with git is based on GitHub flow. Although it is not mandatory to use GitHub, the process is designed to work with GitHub or other vendors that provide branch protection and pull request reviews.

Configuration

Configuring Git as a backend for the architecture change management process is done from the CompliancePal web UI. You have to select a repository from the list of repositories that are assigned to the project.

CompliancePal creates a new commit with the current version of the software architecture specification in the default branch of the selected repository.

The software architecture specification is maintained in the selected repository default branch. The default branch should be protected so that it can be modified only via pull requests. The default branch is the source of truth for the software architecture specification.

Create the draft

A change to the software architecture specification is initiated by creating a new branch from the default branch. The new branch corresponds to an architecture Draft. The Draft branch is not protected and can be modified by anyone in the team.

When opening the pull request, CompliancePal creates a check with status failed that prevents the branch to be merged until the architecture change is reviewed.

Approve the draft

The team member responsible can approve the architecture change using the CompliancePal user interface or by commenting on the pull request.

The approval is recorded in the pull request by the architecture check.

Editing the draft

A pull request can be merged only if the draft is in the Approved state. If new changes are pushed to the Draft branch, the Approved state is removed and the pull request is marked as Open.

Merging the draft

When the pull request is merged, the changes are merged into the default branch resulting in a new version of the software architecture specification.

States and events mapping

The state machine corresponding to this process process is described in the following diagram:

The mapping between the states and transitions of the state machine and the corresponding GitHub events is described in the following table:

Transition	CompliancePal	GitHub event	Description
create	-	pull_request.opened	A new draft is created.
edit	edit	pull_request.synchronize or pull_request.edit	The draft is edited either from the CompliancePal web UI or by adding new commit to the branch. The draft title can be changed by editing the pull request title.
approve	approve	issue_comment.created	The draft is approved either from CompliancePal web UI or with a comment in the pull request.
merge	-	pull_request.closed	The draft is merged from GitHub.