Mantra how-to guide

Components versioning

How to use correctly a version strategy for your components

06-Mar-2022
A  A  A 

Mantra components are, say, pieces of code that solves an specific functionality within your project.

As any other kind of software component (library, module of project), versioning it correctly is a must.

You set the current version of a component in mantra.json component file, like in this example:

{
   "name": "my component",
   "version": "1.0.2"
}

Have a look to component definition documentation to know more.

Actually "name" and "version" properties of mantra.json file are the only mandatory fields needed.

Mantra is flexible about how you version your components: you can use incremental numbers (1,2,3...), or letters indeed (a,b,c...), or the common semantic version strategy (1.0.0, 1.0.1, 1.2.0 and so on).

The version strategy for your components is your responsability and you choose the best one to afford your requirements.

Anyway, it's important to understand that Mantra, when checks that a component has changed its version, ask you to run "update" command:

$ mantrad update

With this command, Mantra updates the new version of the component in core database and check if the component to update implements onUpdate method to perform some specific updating tasks.

Usually, when a data model changes, and you need to update the model in a production system, you need to name the schema with the new version and implement onInstall to update entities to the new schema version.

Given that component named as "niceapicall" has changed its version from 1.0.0 to 2.0.0, and its data model has changed as well, new data model schema named with the new version has to be defined:

niceapicall.2.0.0.schema.json

, and onUpdate method should implement the translation of old entities for version 1.0.0 to entities for the new version 2.0.0, something easy to do with Mantra framework API.

Remember: Mantra expects that the changes in the production code of a project are frequent and minimal as posible: by doing so, the migrations have very low cost and minimal impact. That's a must specifically in continuous integration and desployment system.