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. |