SP-012-001 Software development management
Version control
| Reason for review | Date | Version id |
|---|---|---|
| First version | 20201124 | 1 |
| Moved the content to qms.legit.health and transformed text to markdown | 20220911 | 2 |
Purpose
This specific procedure must be read together with the general procedure it belong to: GP-012 Design, Redesign and Development. It expands on the instructions for the development teams and it translated some of the weird quality management language into the language that the average joe can understand.
Scope
The design and development process of all our medical devices.
Responsibilities
JD-001
- To approve the entire design and development process of the products according to the initial requirements.
JD-005
- To ensure that the entire process of control, verification and validation of the products design and development is carried out according to the methodology established in the present procedure.
JD-003
- To coordinate the entire design and development process of the products according to the methodology established in the present procedure.
Inputs
- Design input elements.
- User, regulatory, technical and other requirements that must be accomplished.
Outputs
- Technical documentation.
Development
Overview
Our software development life cycle is divided into four fundamental processes, which are:
To manage and record this, we use Atlassian's tools, as follows:
| Process | Tool |
|---|---|
| Requirements | Confluence |
| Activities | Jira and Bitbucket |
| Deliverables | Confluence and Bitbucket |
| Tests | Confluence |
And not only the records are in Atlassian, but also the templates. You can check them out at the Atlassian Global Templates section.
Requirements
Why do we do what we do? Because there is a problem to solve or a need to fulfill. That is why the first thing we do is understand what is the problem we are solving. Then, we define what the solution looks like. And the document in which we contain this information is what we call the requirements.
Requirements can come from requests made by clinicians, patients or members of our team.
Also, requirements may be related to new feature requirements, but they can also be update or upgrade requirements or bug fix requirements. This procedure focuses on new feature requirements, since the other two correspond to software maintenance.
To record requirements, we use a template that contains information about who requests the requirement, how important it is and what are the metrics for success. Then, then we lay out the activities that arise to fulfill this requirement. However, before carrying out the activities, the supervisor must approve this requirement.
1. Major requirements
When the requirement affects the core medical features of the device, such as the diagnostic feature, we call them major requirements. They require approval by the JD-005.
It is also worth mentioning that the release of a change that comes from a major requirement implies the creation of a new version of the product, as follows:
2. Minor requirements
When the requirement does not affect the core medical features of the device, such as the diagnostic feature, we call them minor requirements. They also require approval by the JD-005.
The release of a change that comes from a minor requirement gives place to a new intermediate version of the product, as follows:
3. Functional requirements
When the requirement affects the more technical or structural aspects of the software, such as structuring databases or refactoring code, that have no impact over the use of the device, we call them functional requirements. They should be quick to implement and do not require approval by the JD-005.
The release of a change that comes from a minor requirement gives place to a new intermediate version of the product, as follows:
Approval of requirements
| Deployment | Approval |
|---|---|
| Major | JD-005 |
| Minor | JD-005 |
| Functional | JD-005, JD-003, JD-009, JD-010 |
Avoiding collision in the release
| Requirement type | Can be released alongside |
|---|---|
| Major | Functional, Minor |
| Minor | Functional |
| Functional | Minor |
In the event that, for example, a Minor requirement is ready for release, but a Functional requirement is being worked on, the Minor requirement will be awaiting the release of the Functional, and once the Functional requirement has been integrated into the Minor, it will be published.
Template for requirements
In the space for our requirements, when we create a page, they automatically follow the layout and content of the template for requirements, which is stored in Altassian.
This information is contained in the Requirements section of the GP-012.
Managing requirements
As mentioned, we use the Atlassian applications to manage our development lifecycle. More specifically, we use Confluence to document our requirements.
Confluence is a cloud document management application that is specially optimized for digital team processes. It is part of the Atlassian family, so an Atlassian account is required to sign in.
Confluence has spaces, in which we store the knowledge acquired in different areas. One of these spaces is the space dedicated precisely to the requirements.
In these spaces, we create pages. In this sense, a page constitutes a documentary unit.
The cool thing about Atlassian is that Confluence is integrated with Jira, the task and activity manager that we use. In this way, when an activity is mentioned in a requirement, this activity is automatically linked; and vice versa: the requirement appears in the activity.
Also, by mentioning a team member in the document, they are notified and a link is created that includes their contact information.
Confluence has all the necessary security measures we need, as well as the ability to export in PDF or keep a history of versions.
Activities
Once the requirements are done, we make them happen. In other words, we carry out a series of activities.
To manage this, we use Jira. In Jira, each activity is an issue that progresses through it's completion. This issue follows a template that includes information such as the date for completion, the person leading the activity and a link to the requirement is comes from.
This information is contained in the Activities section of the GP-012.
In Jira, activities may have children issues, called tasks.
The tasks and the activity are linked in such way that the information from tasks is available at the activity level.
The activity will be marked as complete once all associated tasks are finished.
Template for activities
When we create a new activity in Jira, the layout and the properties will be inherited from the template. In other words, in Jira the activities automatically follow the template for activities, which is stored in Atlassian.
The information about the template is contained in the Activities section of the GP-012.
Managing activities
As mentioned, we use the Atlassian applications to manage our development lifecycle. More specifically, we use Jira to document our activities.
Jira is a tasks management application that is specially optimized for digital team processes. It is part of the Atlassian family, so an Atlassian account is required to sign in. Jira already has many of the functionalities that are necessary to comply with quality management.
Jira has boards, in which we manage and coordinate the work we are doing. One of these boards is the board dedicated precisely to the activities.
The cool thing about Atlassian is that Confluence is integrated with Jira. In this way, when an activity is mentioned in a requirement, this activity is automatically linked; and vice versa: the requirement appears in the activity. The same goes for the deliverables.
Jira has all the necessary security measures we need, as well as the ability to sign records digitaly in a way that is compliant with digital signature regulations.
It's also worth mentioning that Jira has a view Roadmap that automatically generates the GANTT diagrams from the activities, and even shows the tasks that belong to each activity.
It's worth mentioning that, to manage the code itself, we use another atlassian tool, called Bitbucket. Bitbucket is a web-based repository hosting service for development and source code projects using Mercurial or Git revision control systems. We use the Git system to control the development of the software. This is not particular to us: practically all software companies use Git to keep track of software. In this regard, we follow the following procedure:
- Once a task has been assigned to a developer, the first step is to move the task tab to "In Progress" in Jira, which means that the developer is working on it.
- The developer then creates a new branch in code on Bitbucket from the master branch, whose name corresponds to the activity's code and name.
- Once the task is complete, the developer will mark it in Jira as "Done". And it will be the person responsible for the activity, in case it is different, who will mark the task as finished in the corresponding activity.
This process ensures the traceability of the software developed with the defined activities and tasks.
Deliverables
When we have finished the activities, the result is called a deliverable. In most cases, a deliverable will be a part of the software on which to perform the tests.
These deliverables represent the end of one or more activities and on which a series of tests will be generated.
If there are tests that are not passed, these generate new activities to correct the errors found. This means that the activities end regardless of whether there are errors in the deliverables or not, they are the deliverables, which, if they do not pass the tests, generate new activities.
Managing deliverables
As mentioned, we use the Atlassian applications to manage our development lifecycle. More specifically, we use Confluence to document our deliverables.
Confluence is a cloud document management application that is specially optimized for digital team processes. It is part of the Atlassian family, so an Atlassian account is required to sign in.
Confluence has spaces, in which we store the knowledge acquired in different areas. One of these spaces is the space dedicated precisely to the deliverables.
In these spaces, we create pages. In this sense, a page constitutes a documentary unit.
When an activity is mentioned in a deliverable, this activity is automatically linked; and vice versa: the deliverable appears in the activity.
Template for deliverables
In the space for our deliverables, when we create a page, they automatically follow the layout and content of the template for deliverables, which is stored in Altassian.
The information about the template is contained in the Deliverables section of the GP-012.
Tests
So finally we have done our work and we think it's ready for our users. But before we release it, we need to test it. For that purpose, we use tests. In other words, tests are the systematic evaluations of the deliverables.
Once the deliverable is tested, it can be approved or not. I it is approved, we consider the requirements, activities and deliverables associated with the test as approved. If the deliverable does not pass the test, then we create new activities and repeat the process.
It's worth mentioning that tests can be very different between each other, depending what we are testing. For instance, we can conduct functional Tests (also called black box). These are tests on the software modules and that verify that a technical requirement is met. However, we may also want to conduct user acceptance tests (UAT) when we want to involve actual users to see how they interact with the product.
Testing also takes into account information security considerations, following best practices from the industry (such as the OWASP® Foundation's OWASP Top 10 framework) and aligned with ISO/IEC 27001:2022.
We also carry out penetration testing to discover vulnerabilities and protect the device from threats. We use Intruder, an automated pentesting tool that continuously monitors the device for cyber threats.
And regarding component testing, the device incorporates Cypress for both Component Testing and E2E Testing, which is performed automatically at the activity stage, in such a way that the code cannot even pass the activity stage if there is an error. Even so, the testing stage we run the component testing to verify the deliverable.
Managing tests
We use Confluence to document our tests. Confluence has spaces, in which we store the knowledge acquired in different areas. One of these spaces is the space dedicated precisely to the tests.
When a deliverable is mentioned in a tests, this tests is automatically linked; and vice versa: the tests appears in the deliverable.
Template for tests
In the space for our tests, when we create a page, they automatically follow the layout and content of the template for tests, which is stored in Altassian.
The information about the template is contained in the Tests section of the GP-012.
Test examples
- Feature testing: when we are testing features of the device, we may want to extract metric about the accuracy, sensibility of specificity.
- Platform testing: when we test the interfaces that users use to write or read data.
- Integration testing: we we are testing the code or achitecture related to the integration of the device with third parties.
- Medical testing: when we carry out tests with the specialists of a medical center to ensure that we achieved what they were specifically looking for.
- Patient testing: likewise, we may want to test if patients are happy with a feature, specially if it's somehow related to patients (which should not be the norm, as we are a clinical decision support tool for healthcare professionals).
Version release
We also use Confluence, in a specific space for version releases, where we create pages follwing a specific template, that is stored in Atlassian.
Everything related to the version release is explained in the Version release section of the GP-012.
Deployment of changes
The deployment of changes happens differently depending on the repository.
Deployment in the backend
To send the last approved version of the back to production, that is, deploy the updates, the command follows the following order:
First, connect to the server. For this step, it will be necessary to meet the security conditions established by the organization.
ssh -i legit.pem ubuntu@ec2-15-188-52-50.eu-west-3.compute.amazonaws.com
Once on the server, access the appropriate folder
cd /var/www
and run the following scripts:
./deploy_back
Deployment in the frontend
To send the last approved version of the front to production, that is, to deploy the updates, it is first necessary to go to the root of the local folder (not the server).
There, we will add the following environment variable to the .env.local file:
DEPLOY_PEM='path to server access pem file/legit.pem'
Next we will execute the command:
yarn run release:pro
and run the following script:
./deploy_front
And we will wait for the process to finish.
Common errors
Be careful with i18n's multilanguage settings. It is important to verify that the version of the package.json corresponds to the local one.
You never have to run the yarn add command on the remote server; but only in local development. Failure to do so can lead to incompatibilities between dependencies. Instead, on the server you have to run yarn install to achieve the same end.
The complete sequence would be: ./deploy_front
Signature meaning
The signatures for the approval process of this document can be found in the verified commits at the repository for the QMS. As a reference, the team members who are expected to participate in this document and their roles in the approval process, as defined in Annex I Responsibility Matrix of the GP-001, are:
- Author: Team members involved
- Reviewer: JD-003, JD-004
- Approver: JD-001