**Table des matières** [TOC] # Description Dans GitLab, une **release** est une ***snapshot*** du projet (un **livrable**, ***une photographie*** du projet figé à **un instant donné**) et à destination des utilisateurs du projet. Une release est **toujours associée à un `tag git`** afin de marquer le commit associé à la release :::info La création d'une release entraine **dans tous les cas** la création d'un tag ::: :::danger La suppression d'un tag git associé à une release **entraine également la suppresion de la release associée** ::: Une Release peut contenir : - Une *snapshot*/archive du code source du projet générée automatiquement par GitLab au moment de la création de la release - Des [packages génériques](https://docs.gitlab.com/ee/user/packages/generic_packages/index.html) créés en tant qu'**artifacts** de jobs de la pipeline CI. - Des **métadonnées** diverses associées au code de la release - Des ***release notes*** - Des `milestones` associés - Des [`release assets`](https://docs.gitlab.com/ee/user/project/releases/release_fields.html#release-assets) pouvant être des archives de code source, des [*runbooks*](https://docs.gitlab.com/ee/user/project/clusters/runbooks/#:~:text=Runbooks%20are%20a%20collection%20of,or%20troubleshooting%20a%20particular%20system.), des packages, ou des liens ![Release_structure_Plan de travail 1](https://hackmd.io/_uploads/SkaeQKBda.png) Un fichier **JSON** nommé [`release evidence`](https://docs.gitlab.com/ee/user/project/releases/release_evidence.html) listant tous les artifacts et milestones de la release est également généré automatiquement par GitLab à des fins de comparaison et audit des releases du projet. Ex : ![image](https://hackmd.io/_uploads/SyyhkKB_p.png) # Lister les releases d'un projet ## Par l'interface web de GitLab - Menu **Deploy > Releases** de la barre de navigation de gauche ![image](https://hackmd.io/_uploads/HJjI-YrO6.png) - Sur la page générale du projet, onglet **Releases** ![image](https://hackmd.io/_uploads/HJuoWKHOp.png) # Création d'une release Il existe plusieurs moyens de créer une release : - Via un *job* dans la pipeline CI/CD - Via la page *Releases* de l'interface web GitLab ![image](https://hackmd.io/_uploads/BkOvVtHu6.png) - Via l'[API GitLab](https://docs.gitlab.com/ee/api/releases/index.html#create-a-release) (enpoint `POST /projects/:id/releases`) :::success L'idéal pour nous serait sans doute d'automatiser la création de releases [dès la creation d'un tag SemVer](https://about.gitlab.com/blog/2023/11/01/tutorial-automated-release-and-release-notes-with-gitlab/) ou le merge du code sur une branch via la pipeline CI ::: # Numérotation des releases La nomenclature des numéros de release, ou numéros de version, peut être diverse, mais un formalisme communément admis est celui défini par le standard [Semantic Versioning 2.0.0](https://semver.org/) (aka SemVer) :::info Reprise syntétique du standard SemVer : [Lien](https://medium.com/@balajidharma/how-to-manage-your-application-releases-with-semantic-versioning-d2c580ff9d24) ::: ## Semantic versioning 2.0.0 Structure des numéros de version du projet : ![image](https://hackmd.io/_uploads/r18Yttrua.png) | Symbole | Signification | | -------------------------------------- | ------------- | | <font color="#32AA4E">**X**</font> | Numéro de version majeure (**Major**) | | <font color="#F07E33">**Y**</font> | Numéro de version mineure (**Minor**) | | <font color="#FAEA25">**Z**</font> | Numéro de patch de version (**Patch**) | | <font color="#3798D4">**alpha**</font> | **Nom** de la **pre-release** | | <font color="#9E4C97">**build**</font> | **Numero** de version de la **pre-release** | ### Major Entre deux versions majeures differentes, l'application comporte de **nouvelles fonctionnalitées** et elle n'est **pas compatible avec les versions précédentes** (i.e. *not backward-compatible*). A l'incrementation du numéro de version majeure, les versions mineures et de patch sont reinitialisées à 0. ### Minor Entre deux versions mineures differentes, l'application comporte **nouvelles fonctionnalitées secondaires** présevant la **rétrocompatibilité**. A l'incrementation du numéro de version mineure, le numero de version de patch est reinitialisée à 0. ### Patch Entre deux patchs de version differents, des **corrections de bugs** (i.e. *bug fixes*) préservant la rétrocompatibilité sont apportés à l'application. ### Pre-release & Build Le nom et le numero de build de la pre release sont facultatifs. Ils sont utilisés lors de la publication d'alpha et de beta. :::info [**Alpha Testing vs Beta Testing**](https://www.practitest.com/resource-center/article/alpha-testing-vs-beta-testing/#:~:text=Key%20Differences&text=Alpha%20Testing%20is%20done%20within,tested%20to%20the%20same%20depth.) **Version Alpha :** Version servant à la réalisation de tests d'acceptance par des membres de l'organisation developpant l'application. **Version Beta :** Version servant à la réalisation de tests d'acceptance par des utilisateurs finaux, externes à l'organisation developpant l'application. ::: ### Examples de Semantic versioning 2.0.0 - **16.5.1** (IOS) - **10.1.0-alpha1** (Drupal) #### Préfixe "v" Le standard SemVer ne preconise pas l'utilisation du préfixe "v" devant le numero de version. :::warning **v10.2.5** (Laravel) n'est **pas un numéro de version** au format SemVer ::: Il s'agit cependant d'une **pratique courante**, largement admise et utilisée, nottament au sein des forges afin de **différencier les tags liés aux releases** des autres tags. ## Autres Standard de numérotation des versions D'autres standard de numérotation des version d'un logiciel existent, mais sont moins répandues que *SemVer* ### [Calendar Versioning](https://calver.org/) (aka CalVer) Numerotation **basée sur la date de publication de la release** :::info C'est la numérotaion utilisée pour les versions d'**Ubuntu** : | Date de publication | Numéro de version | | ------------------- | ----------------- | | **Avril** 20**22** | **22**.**04** | ::: ### Name versioning Version **associé à un nom** plutôt qu'un numéro. Utilisé pour les version d'Android : *Lollipop*, *KitKat*, *Jelly Bean*, ... # Lexique ## `artifact` Fichiers ou dossiers créés au sein d'un jobs de la pipeline CI. Ils sont utiles afin de rendre accessibles des fichiers entre des jobs differents de la pipeline CI et depuis l'interface web GitLab. Ex : ![image](https://hackmd.io/_uploads/SyseRdrOp.png) ## `runbook` Collection de procedures et de fonction documentées, souvent utilisé pour accompagner une processus de code de descriptions. Ils sont executées par des **Notebooks** comme [JupyterLab](https://jupyter.org/) Ex : ![image](https://hackmd.io/_uploads/SyseRdrOp.png)