Development workflow¶
This section describes the general principles of the development workflow we implemented. The branching model is presented along with the different use cases.
Description of the different steps¶
Step 1 - software development¶
This step includes several tasks:
write the code to implement the expected functionalities from the specifications that have been formalized.
perform a set of testing that consists of several levels:
unit testing confirms that a piece of code provides the expected output according to the input parameters. The developer is in charge of this testing.
integration testing checks that the interfaces of the different bioinformatics pipeline components are consistent with each other. It ensures that their integration allows the expected functionalities to be performed.
system (or functional) testing validates that the full bioinformatics pipeline works and fits well the user’s needs as they were expressed. A person other than the developer is ideally responsible for carrying out these tests (if the team size allows it).
regression testing checks that the correction of bugs or the development of new functionalities did not introduced defects in unchanged areas of the bioinformatics pipeline. New test cases are added whenever a new release is developed. The set of testing is entirely performed for each new release.
Note
For more details about software testing visit the International Software Testing Qualifications Board.
Step 2 - acceptance testing¶
Once all the testing from the Step 1 - software development is successful, the end-user must validate all the functionalities that have been developed in a mirror environment that is used in production.
Different representative use cases must be evaluated on real datasets. For a bioinformatics pipeline that includes several components (as it is generally the case for bioinformatics pipelines), it is necessary to check that no data are lost between the different processing steps. For example:
if the bioinformatics pipeline annotates a list of genomic variants, then the number of variants used as input must be the same in the output and their genomic coordinates must remain unchanged after the processing.
if the bioinformatics pipeline is a visualization interface, the integrity of the data that are displayed must be preserved.
If the end-user does not validate the developments, the Step 1 - software development starts again.
After the final validation by the end-user, an operational testing is set up in GitLab CI/CD.
Important
The operational testing is essential as it checks that the bioinformatics pipeline provides the expected results on a reference dataset (golden dataset) in the production environment. This testing is performed periodically to ensure the reproducibility of the results.
Step 3 - check the installation process and new testing¶
This steps checks that the bioinformatics pipeline can be installed in a similar environment that is used in production.
Another set of testing is performed such that bugs can be corrected before installing the bioinformatics pipeline in production.
This step should be realized within a very short period of time. The bioinformatics pipeline is generally deployed in the production environment right after this step.
Step 4 - production deployment¶
During this last step, the new release of the bioinformatics pipeline with the new functionalities is installed in the production environment.
Multiple deployment environments¶
It is mandatory that the different steps that have been previously described are performed in separated environments for the following reasons:
ensure that a stable version can be used in production,
allow the end-users to validate a new release without any impact on both the version used in production or the version under development,
allow the software developers to add new functionalities and modify the code without any impact on the end-users who are validating a new version and/or using the version currently in production.
Therefore, we use 3 deployment environments for the bioinformatics pipeline:
dev: development environment
valid: validation environment (also called pre-production)
prod: production environment
Each bioinformatics pipeline has 3 environments that are accessible in dedicated folders. For example, the environments of the bioinformatics pipeline foobar would be located here:
/bioinfo/pipelines/foobar/dev/bioinfo/pipelines/foobar/valid/bioinfo/pipelines/foobar/prod
Note
The deployment environments are not limited to the 3 environments that have been previously described. Indeed, each developer can deploy the bioinformatics pipeline in a local workspace to test the new functionalities. The deployment in the dev environment generally takes place when a preliminary set of testing has been sucessful.
Version control and branching model¶
The management of the different bioinformatics pipeline versions is based on different git branches. Each branch is used depending on the context and the step in the development workflow. The model we use is based on a remote repository that contains 4 branches:
devel: contains the code of the current version under development. Note that the version under development may have not been yet deployed in the dev environment. The code remains on that branch while the bioinformatics pipeline has not successfully passed the Step 2 - acceptance testing.
release: contains the code with both candidate and official releases. The release branch comes from the devel branch.
hotfix: this branch is a mirror of the release branch and is used to patch the code that is in production. If a critical bug occurs in production, this branch is used to fix the issue.
main: this branch is not used for development, it is only used to archive the code from the release and hotfix branches.
Among these four branches, the release, main and hotfix are protected branches. This means that only the developer with the Maintainer role in the GitLab repository can push code on the remote repository. Other developers have to Create a Merge Request in Gitlab to submit their modifications to the Maintainer.
The developer will have to create local branches in the local workspace used for development whenever a new feature is implemented, a hotfix is resolved or problem occurred during the Step 3 - check the installation process and new testing. Therefore, the local workspace will contain:
the branches from the remote repository,
the local branches created by the developer to implement the new feature. These branches will not be sent onto the remote repository. They are named with the prefix feature and any meaningful suffix (e.g feature_star_mapper),
the branches that developer will use to Create a Merge Request in Gitlab on protected branches. These branches will have either the prefix release or hotfix depending on the context.
The workflow across the different branches can be summarized in the graphic below:
Warning
No development must be initiated on a branch that exists on the remote repository. The developer always creates a local branch with the command git checkout -b feature_1 (or any other more meaningful suffix). The modifications are committed on the local branch. Once validated, the modifications are merged on the branch from which the local branch was created.
Deployment and branching model¶
There is no bijection between the branches and the deployement environments as a version from a given branch can be deployed in different environments. However, only some combinations are allowed as described in the table below:
env:dev |
env:valid |
env:prod |
|
|---|---|---|---|
branch:devel |
|
|
|
branch:release |
|
|
|
branch:hotfix |
|
|
|
branch:main |
|
|
|
is the normal case
is a prohibited case
is possible case
is the normal case when both the Step 2 - acceptance testing and the Step 3 - check the installation process and new testing are successful
is an exceptional use case
Steps of the workflow and deployment environment¶
During the different steps of the workflow, the deployment of the bioinformatics pipeline is performed in the following environments:
environment |
|
|---|---|
dev |
|
dev |
|
valid |
|
prod |
User roles and permissions¶
In the gitlab remote repository¶
In the remote repository on GitLab, the projects members will be assigned one of the following role:
Developer: the user can push the developments on the non-protected branches. The letter D is used as an abbreviation for this role.
Maintainer: in addition to the permissions with the Developer role, the user can push on the protected branches. The letter M is used as an abbreviation for this role.
In the deployment environments¶
For the deployment, two roles are considered:
UD: the user can deploy in the dev environment.
UVP: the user can deploy in the valid and prod environments.
Note
Whenever necessary, the roles that are required to perform the different actions will be mentioned. For example, M+UVP means that the user must have the Maintainer role in gitlab and can deploy in both the valid or prod environments.