...
In addition, we can generate tagged versions of the elements (tags in Git), so that in case of migration or if we want to restore a particular version of the elements, we can do it without problems.
Requisitos para habilitar el versionado
Para poder habilitar el versionado de elementos en una instalación de plataforma necesitaremos:
Repositorio Git (GitHub o GitLab) con un token de API con permisos de escritura
Role administrator: solo los administradores pueden configurar esta funcionalidad
Configuración del repositorio Git
En primer lugar, tendremos que configurar el repositorio Git que va a utilizar la plataforma para ir versionando los elementos. La plataforma trabajará siempre en la misma rama de Git establecida en la configuración.
...
Requirements to enable versioning
In order to enable the versioning of elements in a platform installation we will need:
Git repository (GitHub or GitLab) with an API token with writing permissions.
Administrator role: only administrators can configure this functionality.
Git repository configuration
Firstly, we will have to configure the Git repository that the platform will use to version the elements. The platform will always work in the same Git branch that is established in the configuration.
To configure it, we will go to the menu > Version Control > Configuration
...
Aquí rellenaremos todos los campos necesarios y marcaremos la opción de crear repositorio si así lo deseamos:
...
En caso de tener ya un repositorio creado, desmarcar la opción.
...
Una vez configurado, podremos modificar la configuración en cualquier momento, incluso deshabilitar el versionado de recursos temporalmente (botón arriba a la izquierda). También podremos borrar directamente la configuración.
...
Además, en el momento de configurarlo, se nos generará un SNAPSHOT de los recursos actuales en el repositorio:
...
Formato de serialización de los elementos
Para serializar las entidades o elementos del sistema de versionado, hemos elegido el formato Yaml, ya que para elementos como los Dashboards o Gadgets, nos permite mostrar el contenido HTML de manera legible.
...
Además, si queremos editar el fichero para luego restaurarlo, será mucho más sencillo.
Mensaje de commit en edición y creación
Cuando se habilita el sistema de versionado, nos empezaran a aparecer pop-ups con un cuadro de texto para introducir un mensaje de commit a la hora de crear o actualizar elementos versionables.
Por ejemplo, al editar una ontología:
...
Si dejamos el commit vacío, se pondrá un mensaje de commit genérico, indicando el usuario que ha editado o creado el elemento.
Histórico de cambios, restauración y edición de un elemento
En la opción de menú Restore Resource, disponible para todos los usuarios que tengan role igual o superior a developer, se nos abrirá una pantalla en la que podremos ver el histórico de cambios para cualquier elemento al que tengamos acceso, restaurarlo e incluso modificar la versión actual.
...
Seleccionando un commit concreto, nos aparecerá un visor con las diferencias existentes entre el elemento actual (editable, a la derecha) y el elemento en el commit seleccionado (a la izquierda, no editable).
Una vez aquí, podremos restaurar la versión del commit (botón Restore), o editar la versión actual para mergear cambios, por ejemplo. Para editar la versión actual, modificaremos el contenido del elemento en el editor, y pulsaremos en Here we will fill in all the necessary fields and mark the option to create repository if we want:
...
If we already have a repository created, we uncheck the option.
...
Once configured, we can modify the configuration at any time, including temporarily disabling resource versioning (top left button). We can also delete the configuration altogether.
...
In addition, at the time of configuring it, a SNAPSHOT of the current resources in the repository will be generated:
...
Element Serialization Format
To serialize the entities or elements of the versioning system, we have chosen the Yaml format, because, for elements such as Dashboards or Gadgets, it allows us to display the HTML content in a readable way.
...
Besides, if we want to edit the file and then restore it, it will be much easier.
There are some elements such as Web Projects, Dataflows, flows and notebooks, which in addition to having a serialized file with the information of the database entity, will have an associated zip file (or several ones) that will contain the physical resources of said element. .
...
Commit message on edit and create
When the versioning system is enabled, pop-ups will begin to appear with a text box to enter a commit message when creating or updating versionable elements.
For example, when editing an ontology:
...
If we leave the commit empty, a generic commit message will be used, indicating the user who has edited or created the element.
Commit messages for Dataflows, Flows and Notebooks
As these elements have associated physical disk resources, it is necessary to commit them "manually and intentionally" from their list, using a special button.
...
History of changes, restoration and edition of an element
In the Restore Resource menu option, available to all users who have a role equal to or greater than developer, a screen will open where we can see the history of changes for any element to which we have access, restore it and even modify the current version.
...
Restoring an existing item
If the element currently exists on the platform, we will choose the first option “Restore existing resource”.
...
Here we will get a dropdown with all the platform elements that are versionable.
...
Once the type of element has been selected, a drop-down will appear with the specific element that we want to restore.
...
Finally, when selecting the element to restore, a dropdown will appear with the commits. When one element is selected, we will be shown the content of the element in that commit.
...
A code viewer will appear with the differences between the current element (editable, to the right) and the element in the selected commit (not editable, to the left).
Once there, we can restore the commit version (Restore button), or edit the current version to merge changes, for example. To edit the current version, we will modify the content of the element in the editor, and click on Save Changes (cmd + s / ctrl + s).
...
Creación de un Tag de versión
En cualquier momento, podremos generar un tag de git y asignar la versión actual (SNAPSHOT) de todos los elementos versionables.
...
Restaurar la plataforma
Con esta funcionalidad también podemos restaurar todos los elementos de plataforma desde un repositorio git indicando un tag o branch.
...
También se puede realizar este proceso para migrar/promocionar entornos, por ejemplo, para llevarse los elementos de un entorno de desarrollo a uno de pre-producción.
Este proceso borrará todos los elementos versionables que no se encuentren en el repositorio Git.
Modificación de elementos desde repositorio Git
Es posible también modificar los elementos manualmente desde el repositorio, y después restaurarlos en plataforma, uno a uno o para restaurar el conjunto de los elementos de la plataforma.
...
Restoring a deleted item
In case we want to recover an element that was deleted in a commit, we can do it from the “Restored deleted entity” option.
...
Here we will choose the type of entity, the relative path to the item in the Git repository, and the commit from where we want to restore it. Finally we will select “Load content” to verify that the content is correct and then “Restore”.
...
Git Snapshot and Tag Creation
We can generate a Snapshot of the platform’s versionable elements at any time.
...
Snapshot with all elements
If we want to generate a version including all the elements, we should make sure that all the elements are checked.
In this case, the Tag name will be optional.
Snapshot with selected items
If we want to generate a version with only certain elements of the system, we will have to mark only the resources that we want to include.
Bear in mind that, if we uncheck users, the resources associated with those users will be automatically excluded, even if they are checked.
...
In this case it will be necessary to indicate the name of the Git Tag.
...
Restore the platform
With this functionality, we can also restore all the platform elements from a Git repository indicating a tag or branch.
...
This process can also be done to migrate/promote environments, for example, to move elements from a development environment to a pre-production environment.
This process will delete all versionable items that are not in the Git repository.
Modifying items from Git repository
It is also possible to manually modify elements from the repository, and then restore them to the platform.
To do this, we will go to any versioning screen (for non-administrator users, Restore Resource screen), and look for the “Sync repository” button.
...
This will synchronize the changes with the database.