Integration
Previous Steps
Before reading the Integration documentation, you need to choose a versioning scheme for your project. Then, refer to your scheme's step-by-step integration guide.
In the integration instance, you merge all changes together in the same development or delivery branch. In Studio, this integration is done through merge requests (also referred to as MR).
When a branch is created, it starts from the last commit of the source branch. While this new branch evolves, the source branch can continue to receive changes. At the time of the merge, Git analyzes the most recent common point between the two branches (known as the common ancestor) and, from there, determines what changes each branch introduced. That is to say, Git does not compare branch against branch before a merge, but it compares branch against a common commit ancestor instead. This allows to calculate the differences between branches and apply changes.
Read the creation standards to learn how to properly create a merge request, and then refer to the merging standards to learn what are the basics of merging and how to merge branches in each versioning scheme.
Merge Request creation standards
Since MRs do not show the differences or commit history in Studio, the description of the MR becomes the main source of information about what is being integrated. Therefore, it is essential to maintain a clear and detailed convention to facilitate review, traceability and testing in the team.
Follow the guidelines below when creating new merge requests in Studio:
The title should include the type of change (feature, fix, etc.), the name of the functionality and, if applicable, the ticket number. Example: [FEATURE] Biometric Login - Ticket #1234 Description.
The description should include a brief summary of what has been done, functionalities added, changes on entities that are stored in the database and developer in charge. Example:
Includes: Validation by fingerprint. Automatic redirection if session is active. Log of failed attempts (new table). Database changes (essential for release branch merge): Site Param: Value 55 in KEYVALUE Error handler: OnError V01:contents1|S432 Developer in charge: John Doe
Merging standards
Even though each versioning scheme has its own merging guidelines and best practices, there are a set of basic merging standards that apply to any of the versioning strategies selected.
Merge branches only when their development is complete, tested and functionally validated. It must represent a stable, self-contained working unit aligned with the defined requirements.
Do not merge a branch with partial or ongoing changes, as this may introduce unexpected behavior, break other functionality or make it difficult to identify errors.
In the case of feature or hotfix branches, merge only when:
conflicts (if any) were resolved;
changes were properly documented (affected entities, impact on database if applicable, etc.);
the functionality is part of the delivery to the client.
In the case of release branches, merge only when the delivery is approved by QA and confirmed for production release. From that point on, the branch can be integrated into main and develop (in the trunk-based scheme), or serve as the basis for the next release (in the feature-based scheme).
To minimize errors when integrating elements stored in the database, you must:
explicitly list in the MR description all the modified entities in the database with their corresponding values (which allows the Release Manager to validate and manually apply the necessary changes); and
compare each feature branch with its integration branch using DeltaComparator to identify differences in non-versioned entities.
See below for merging standards for each versioning scheme. Then, if you get conflicts while merging, read Conflicts Resolution to learn how to proceed, depending on the scheme selected.
The feature-based scheme presents three different merge opportunities, with one of them being mandatory. Additionally, there are two merge opportunities when a bug arises.
Before integrating a feature or hotfix branch to the release branch, it is highly suggested to update it with the latest release changes. To do this, perform a pull in Studio by creating a merge request with the release branch as a source and the feature branch as target. Even if there are no conflicts detected, it is good practice to validate that the release changes are present before integrating. Read Resolving conflicts in the release branch if this pull presents conflicts.
Once the previously defined functional and technical conditions are met (i.e. the development is finished, tested and confirmed for delivery), integrate the changes into the release branch through a merge request. If the pull was already executed, this merge should not generate any conflicts.
Important
This step is mandatory.
Once the release goes to production, perform a merge to the main branch to keep a clear traceability of the deliverables and to have a picture of the production instance. Although the scheme can work without this step (especially since the database is updated manually), this integration promotes version control. This merge should not generate conflicts.
Bug fixing: Once a fix to a productive bug has been developed, tested and validated, merge the hotfix branch to the release branch and generate a new release from it. This is mandatory when a bug is found in production.
Bug fixing: It is mandatory to perform a pull from that release branch (with the fix applied) to the next active release. This ensures that the next release will also contain the hotfix. Failure to do so risks re-releasing the same bug to production in the next release. This pull may generate conflicts if changes were made to the same file in the release branch.
Important
It is not necessary to perform a pull from the main to the release branch before integrating feature or hotfix branches. In this scheme, the main branch has no changes of its own or active development, but only receives merges from release. Therefore, there are no changes in main to be incorporated into the release branch.
The trunk-based scheme presents an optional merge opportunity when there are no bugs detected in production. When there are bugs and a hotfix is created from the productive release branch, there are three merge opportunities, which are mandatory.
Once a release goes to production, perform a merge from release to the main branch to keep a clear traceability of the deliverables and to have a picture of the production instance. Although the scheme can work without this step (especially since the database is updated manually), integrating it promotes version control. This merge should not generate conflicts.
Bug fixing: Once the fix has been developed, tested and validated, merge the hotfix branch back to the release branch and generate a new release from it. This merge should not generate conflicts.
Bug fixing: Perform a pull from the new release (with the fix applied) to the next active release branch. This ensures that the next release will also contain the hotfix. Failure to do so risks re-releasing the same bug to production in the next release. This merge can generate conflicts.
Bug fixing: Perform a merge from the release branch to the develop branch. This way, our development branch has the productive fix. This merge should not generate conflicts.
Reverting a merge
On certain occasions, it may be necessary to undo an integration. This can happen:
if a feature was merged by mistake and was not supposed to be part of the release;
after an integration a critical bug is detected that prevents its delivery; or
a certain feature is not be included in the final version.
In these cases, it is important to understand what options we have to reverse the integration or restore the previous state of the branch.
Returning a branch to a previous point or reversing a merge is technically possible. However, due to the particular implementation of the link between Studio and GitLab, it is not recommended to do this on a standalone basis, as it involves additional manual processes that must be carefully executed.