Skip to main content

Veritran Docs

Versioning Schemes

Previous steps

Read Versioning Definition and Implementation to learn when to start branching in your project.

There are two standard versioning schemes that can be applied when working in Studio. The feature-based scheme and the trunk-based scheme.

The feature-based scheme fragments development by functionality. The development is organized into independent branches by features, which are then integrated into a release branch. This is a more robust and orderly model, recommended for projects with constant evolution, multiple functionalities in parallel, large or high turnover, and scenarios where client requirements may change frequently and require flexible planning. Read how to implement this versioning scheme here.

The trunk-based scheme is also known as the unified development model. With this scheme, all development converges directly into a common branch, without prior separation by functionalities. It is simpler to implement and suitable for small teams or projects with less complexity and variability. This model is simpler and consists of a more linear strategy. Read how to implement this versioning scheme here.

Choosing the appropriate scheme will depend on the delivery model, the maturity of the team, the agreements with the client, and the stage of the project. However, the chosen scheme needs to be flexible enough to be adapted upon unpredictable events, such as delays in development and delivery.

Feature-based Versioning Scheme

In the feature-based versioning model, development is organized by having a new functionality per branch. Each branch contains the changes needed to implement a specific feature, which are then integrated into a common release branch when it is decided that this functionality is ready to be delivered. 

optiona.png

This strategy allows for precise control over features that are delivered and their delivery date. It also provides greater traceability and clarity regarding the changes included in a release. 

This scheme is suitable for:

  • medium or large teams with defined management profiles (developers, technical leaders and members in charge of the release);

  • projects with constant evolution and high level of demand from their clients (in auditing and documentation); and

  • projects with functionalities that evolve in parallel and have deliveries that need flexibility.

Standards for versioning with a feature-based approach

These versioning standards are designed to guide users towards a clear, structured branching approach when adopting a feature-based scheme.

  • Create a feature branch per app functionality, and a hotfix branch per reported bug.

  • Add the JIRA ticket number to feature and hotfix branches. Additionally, you can add a brief functionality or fix description. This will help easily identify what is contained within the branch.

    Tip

    If fixes are strictly related to one another, you can work related fixes in the same branch and add a description and the JIRA ticket numbers.

How to branch with the feature-based versioning scheme

Who works in the creation of branches?

Release branches must be created by the team leader or member in charge of the releases. Feature and hotfix branches can be created by the technical leader, members in charge of the releases or any developer in the team.

Follow the steps below to start branching with the feature-based versioning scheme, where feature branches always derive from a previously defined release branch:

Important

By default, every repository has a main branch. Work in this branch until you have a solid functional base that allows you to start fragmenting by feature, or until you have a delivery set for a client.

  1. Create a release branch.

  2. Add a clear name to the release branch. It might include the version number to be delivered, the delivery month, or any alias defined with the client.

  3. From this release branch, create the necessary feature branches to start fragmenting development. They can also be created as new features are detected or requested.

  4. In each feature branch, include the JIRA ticket linked to the feature implemented and a short descriptive name.

  5. Add a description to each feature branch. The description must contain:

    • Name of the person working on that functionality.

    • Scope of the implementation.

    • Necessary changes to the database. They will be included in the merge request message.

  6. Once the delivery date is set and the implementation is ready, integrate the changes. For more details about the integration step, refer to Integration, and to Conflicts Resolution if any conflicts emerge during the integration step.

  7. Once the integration step finishes, functionalities are validated and the release is delivered to the client, a new cycle begins. This involves creating a new release branch.

    Important

    The new release branch must be created from the previous release branch, and must include every change previously delivered to the client. To validate it is being created from the correct branch, verify the previous release branch appears in the from field in the Overview page in Studio.

    Notice

    If any feature was left out from this release, it can be included in the next release.

  8. In future cycles, it might be necessary to fix any detected bugs from the previous delivery. For this, create as many hotfix branches as necessary, taking this into consideration:

    • If the fix is urgent, create the hotfix branch from the delivered release branch (i.e. version 1.0.0), and create a new version (i.e. version 1.0.1).

    • If the fix can be introduced in the following delivery, create the hotfix branch from the ongoing release (i.e. 1.1.0).

    • Use the same naming convention as with release and feature branches by adding a brief descriptive name and the JIRA ticket number.

Read Removing Branches for standards on how to remove branches after a delivery.

Trunk-based Versioning Scheme

In this model, all developments are made in one branch only (development branch), without separation by functionality. When a decision is made to deliver to the client, a release branch is created from the develop branch, containing the current state of development.

trunkbased.png

This approach aims to simplify the versioning process, reducing the number of active branches and minimizing branch management work, beneficial to small teams mostly.

The trunk-based scheme is suitable for small or medium-sized projects, which can easily coordinate their work; small or medium-sized projects without much post-delivery evolution, with functional deliveries set closely with the client, and low levels of audit requirements.

Standards for versioning with a trunk-based approach

These versioning standards are designed to guide users towards a clear, structured branching approach when adopting a trunk-based scheme.

  • To improve traceability, it is recommended to record in the description of each release branch the JIRA tickets included, together with a functional summary. This allows for clearer tracking without modifying the branch structure.

  • It is suggested to work continuously in the develop branch, generate a release branch at the time of a delivery to a client, test on that branch, and once approved, merge to the main branch.

How to branch with the trunk-based versioning scheme

Who works in the creation of branches?

Release branches must be created by the team leader or Release Manager. Feature and hotfix branches can be created by the technical leader, Release Manager or any developer in the team.

Read below for a step-by-step detail on how to work with a trunk-based versioning model within your project.

Important

By default, every repository has a main branch. Work in this branch until you have a solid functional base that allows you to start fragmenting by feature, or until you have a delivery set for a client.

  1. Create a develop branch. This branch will have all the daily work centralized in it.

  2. When it is time to deliver a functionality to the client, create a release branch from the develop branch. This branch is used to perform the corresponding tests and is delivered to the QA team for certification.

  3. While QA tests the release, developers can resume working on the develop branch to include further deliveries.

  4. The QA team might detect any bugs from the previous delivery. If that is the case, you can fix them taking this into consideration:

    • If the bug is not critical, fix it directly in the develop branch, to be part of the next release.

    • If the bug is critical and requires an immediate fix, create a hotfix branch from the affected release, fix the bug, test it and integrate into the release. Finally, deliver the corrected release to the QA team.

    • For the hotfix branch, use the same naming convention as with release and feature branches by adding a brief descriptive name and the JIRA ticket number.

  5. Once the release branch goes to production, integrate it to both main and develop branches. The main branch reflects what was delivered to the client, and the develop branch will be kept up to date with any fixes or changes. For more details about the integration step, refer to Integration, and to Conflicts Resolution if any conflicts emerge during the integration step.

  6. If you need to generate a new release when the previous release is still being validated (for example when tests are queued or a hotfix needs to be released), create the new release from develop and restart the cycle from step 1.

In this section: