Utilisation de GIT

Un article de OviWiki.

Sommaire

Introduction

Depuis la version 6.3.0 d'Ovidentia, une nouvelle méthodologie a été mise en place pour la gestion des versions du noyau. Cette méthodologie répond à un certain nombre de besoins concernant le développement, la maintenance et le déploiement d'Ovidentia :

  • Permettre de stabiliser un version d'Ovidentia sans introduire de régressions dues à l'ajout de nouvelles fonctionnalités,
  • Créer rapidement des patches permettant de passer d'une version du noyau à une autre,
  • Faciliter la création des Release Notes à la sortie d'une nouvelle version.

Principe des versions et des branches du noyau dans GIT

Branches stables et instables

Principe des branches stables et instables du noyau ovidentia. Les ronds noirs sont les versions stables sur les branches PATCHS, les ronds blancs sont les versions bêta et les ronds gris les versions Release Candidate.
Principe des branches stables et instables du noyau ovidentia. Les ronds noirs sont les versions stables sur les branches PATCHS, les ronds blancs sont les versions bêta et les ronds gris les versions Release Candidate.

Le travail dans GIT s'éffectue sur deux types de branches : stable et instable. Les caractéristiques de ces types de branches sont les suivantes :

Les branches stables 
Elles sont nommées PATCHS-X-Y-0 dans git. Ces branches ne contiennent que des versions stables. Toutes les versions d'une branche stable ne contiennent que des corrections de bugs par rapport à la version initiale de la branche.
La branche instable 
Elle est nommée master dans git. C'est la branche où ont lieu les nouveaux développements. Elle contient des versions bêta (dont le dernier chiffre est supérieur ou égal à 90) considérées comme instables et des versions release candidate (dont le dernier chiffre est supérieur ou égal à 100) considérées comme stables du point de vue des fonctionnalités mais non testées.

Les modifications peuvent avoir lieu en parallèle sur les différentes branches. En pratique, elles n'auront lieu que sur la dernière branche stable et la branche instable : correction de bugs sur la dernière branche PATCHS-X-Y-0 et ajout de nouvelles fonctionnalités sur HEAD.

En effet, par principe (défini par Cantico) lorsqu'une nouvelle branche PATCHS-X-Y-0 est créée, la branche PATCHS précédente est "fermée" : il n'y aura plus de nouvelle version taggée sur cette branche. Cependant, des correctifs pourront être ponctuellement committés puis diffusés par la gestion des patches de cantico.fr.

Numérotation des versions

Les numéros identifiant les versions d'ovidentia sont composés de trois chiffres séparés par des points. Ils se lisent de la manière suivante :

6 . 5 . 2
|   |   |
|   |   |_ 2ème version de maintenance
|   |
|   |___ 5ème version mineure
|
|_____ 6ème version majeure
  • La version de maintenance est incrémentée lors de la correction de bugs.
  • La version mineure est incrémentée lors d'ajout d'une ou plusieurs petites fonctionnalités.
  • La version majeure est incrémentée lors d'ajout de fonctionnalités importantes.
Versions stables 
Elles ont un numéro de maintenance strictement inférieur à 90. Toutes les versions stables ayant le même numéro de version majeure et mineure disposent du même ensemble de fonctionnalités, proposent les mêmes interfaces aux utilisateurs (hormis les corrections de bugs d'affichage) et gardent la même documentation (hormis les corrections et les ajouts sur des fonctionnalités pas ou peu documentées).
Versions bêta 
Elles ont un numéro de maintenance supérieur ou égal à 90 et strictement inférieur à 100. Les versions bêta intègrent tout ou partie des nouvelles fonctionnalités en cours de développement dans le noyau. Elles peuvent être distribuées mais - étant notoiremment instables - elles ont essentiellement pour but d'offrir un aperçu des évolutions du noyau et de fournir une base commune pour la recherche de bugs.
Versions Release Candidate 
Elles ont un numéro de maintenance supérieur ou égal à 100. Les versions Release Candidate (rc) succèdent aux versions bêta. A partir de la première Release Candidate (rc1), les ajouts fonctionnels sont prohibés (période dite de feature freeze) jusqu'à la création de la prochaine branche stable.

Correction de bugs

Principe

La correction d'un bug s'effectue d'abord sur la dernière branche stable (PATCHS_X_Y_0) du noyau.

Cette correction est ensuite mergée sur la branche instable.

Exemple

Si un bug est constaté sur la version 6.4.3 :

  • Le développeur récupère la dernière version de la branche PATCHS-6-4-0 (checkout ou update s'il avait déjà récupéré cette branche)
  • Qualifie le problème
  • Corrige le bug
  • Fait un commit des fichiers corrigés (toujours sur la branche PATCHS-6-4-0)
  • Fait un merge des fichiers modifiés sur la branche instable (HEAD)
  • Vérifie que la correction fonctionne aussi sur cette branche
  • Fait un commit des fichiers corrigés (sur HEAD)
  • Si nécessaire, fournit le ou les patchs au support par l'intermédiaire de l'application "Gestion des patchs" du portail extranet http://www.cantico.fr

Il appartient au développeur de s'assurer que ses corrections ont été mergées sur la branche instable de git.

Il appartient à la personne qui sort la version X.(Y+1).0 de s'assurer que les branches PATCHS ont bien été mergées.

Commentaires de commit

A chaque commit dans le noyau d'ovidentia, un commentaire décrivant les changements doit être spécifié. Le commentaire doit être en anglais.

Suivant la nature de la modification apportée au noyau, le message peut être préfixé par l'un des mots-clés suivants :

  • BUGM : il s'agit de la correction d'un bug enregistré dans Mantis,
  • ENHANCEMENT : s'il s'agit d'une amélioration,
  • SECURITY : s'il s'agit d'une correction relative à la sécurité,
  • OPTIMIZATION : s'il s'agit d'une optimisation.

Le mot-clé BUGM (et optionnellement les autres mots-clés) doit être suivi du numéro de bug dans Mantis sous la forme #XXX. D'une manière générale, si les commentaires doivent apparaître dans les Releases Notes, il est nécessaire de créer un entrée correspondante dans Mantis (avec une sévérité correspondante) et de faire suivre le mot-clé du numéro du bug créé dans Mantis.

Si la mise à jour est mineure (faute d'orthographe, correction html...), mettez Minor change afin que la personne qui lit le log comprenne que c'est bien une modification mineure.

Commentaire de commit lors d'un merge

Les messages d'un commit sur la branche PATCHS devront être recopiés lors du merge sur la branche principale en ajoutant la mention Merged from PATCHS-X-Y-0.

Exemple de commentaire d'une correction de bug sur la branche PATCHS :

BUGM #124: Error SQL when you try to access calendar

Le commentaire de la même correction de bug mergée sur la branche principale :

BUGM #124: Error SQL when you try to access calendar
Merged from PATCHS-6-2-0


Gestion des versions du noyau dans GIT

Avant chaque sortie de version, un tag correspondant est mis sur la branche : à la version X.Y.Z correspond le tag version-X-Y-Z. Si le dernier chiffre du numéro de la version est zéro, une branche correspondante PATCHS-X-Y-0 est créée.

Exemple :

  • Tag version-6-4-0 sur le tronc et création de la branche PATCHS-6-4-0
    • Tag version-6-4-1 sur la branche PATCHS-6-4-0
    • Tag version-6-4-2 sur la branche PATCHS-6-4-0
  • Tag version-6-5-0 sur le tronc et création de la branche PATCH-6-5-0
    • Tag version-6-5-1 sur la branche PATCHS-6-5-0
    • Tag version-6-5-2 sur la branche PATCHS-6-5-0
    • Tag version-6-5-3 sur la branche PATCHS-6-5-0

Programme de reprise

Lors d'une mise à jour d'ovidentia, tout le programme de reprise est exécuté, il appartient au développeur de faire les tests nécessaires afin de ne pas effectuer une action plusieurs fois.

Depuis la version 6.3.0, un log des mises à jour à été mis en place. Il peut être utilisé au moyen de 2 fonctions (bab_setUpgradeLogMsg et bab_getUpgradeLogMsg) dans le programme de reprise du noyau ou d'un module. Un identifiant unique (par module) peut être déposé avec le message de log puis la fonction bab_getUpgradeLogMsg permet de tester si le message de log existe afin de ne pas exécuter plusieurs fois une partie du programme.

Gestion de versions incompatibles lors d'une mise à jour

Cet exemple illustre l'interdiction de migration d'une version vers une version bêta antérieure.  La version stable 6.5.1 est créée. La version 6.5.90 (6.6.0 bêta 1) est créée. Une nouvelle version stable 6.5.2 est créée. Cette version ne doit pas pouvoir être mise à jour vers la version 6.5.90 (bien que 6.5.90 > 6.5.2) On crée donc une nouvelle version bêta 6.5.91 vers laquelle la 6.5.2 pourra évoluer

Cet exemple illustre l'interdiction de migration d'une version vers une version bêta antérieure.

  1. La version stable 6.5.1 est créée.
  2. La version 6.5.90 (6.6.0 bêta 1) est créée.
  3. Une nouvelle version stable 6.5.2 est créée. Cette version ne doit pas pouvoir être mise à jour vers la version 6.5.90 (bien que 6.5.90 > 6.5.2)
  4. On crée donc une nouvelle version bêta 6.5.91 vers laquelle la 6.5.2 pourra évoluer

Pour chaque version, il sera possible de définir un numéro de version minimal pour l'installation d'origine d'ovidentia, dans le but de forcer des mises à jours par paliers en cas de gros écarts de version. Comme tout le programme est exécuté à chaque mise à jour cela permet de supprimer de temps en temps les parties du programme qui ne sont plus utilisées.

Par principe, il ne devrait être possible de migrer que d'une version d'ovidentia vers une version sortie postérieurement. Par défaut, le programme de reprise autorise la mise à jour si le numéro de la nouvelle version est supérieur à la version en place. Or dans certains cas, si une branche PATCHS-X-Y-0 est prolongée après que la branche stable suivante est sortie, ou plus fréquemment lors de la sortie de versions bêta, ce système autoriserait la mise à jour d'une version récente vers une version plus ancienne : par exemple, d'une 6.5.2 vers une 6.5.90 alors que la 6.5.2 est sortie après la 6.5.90. Pour cette raison, il est possible, dans la configuration, d'interdire la migration d'une version du noyau vers une liste de numéros de versions spécifiées.

exemple dans le fichier version.inc :

forbidden_upgrades="6.3.0,6.3.1"

Développement personnel ou expérimentation

Tout besoin de développement personnel pour des expérimentations doit se faire dans une branche séparée. Le nom de la branche doit porter les initiales du développeur ayant initié la branche. Le nom de la branche commence par les initiales du développeur, un tiret et un libellé. Par exemple : SZ-SYNCHML

Ajouter un projet dans GIT (add-on, script...)

Utiliser bitbucket et créer le projet dans le groupe cantico si vous êtes membre du groupe


Gestion des versions d'un add-on dans GIT

Tout add-on ajouté dans Git doit avoir son entrée dans Mantis pour déposer et suivre ses bugs.

Un fichier history.txt dans le répertoire des fichiers php de l'add-on doit permettre de suivre les différentes sorties de version ainsi que les corrections apportées. La structure de ce fchier est la suivante :

02/07/2007: Version 1.52

- BUGM 1254: Problème sur l'option activation/désactivation de l'autorisation de connexion
- Amélioration
- ....

Les versions d'un module peuvent être gérées de la forme X.Y.Z où :

  • X est la version majeure
  • Y est la version mineure

Le tag git sera le numéro de version.


A chaque sortie d'une version git :

  • Le fichier addonini.php doit être mis à jour (incrémentation de la version)
  • Le fichier history.txt doit être mis à jour (ajout des historiques des modifications)
  • git doit être taggué avec un tag contenant le numéro de version
  • Enfin le numéro de version X.Y.Z doit être créé dans Mantis