Semantic versioning and releasing made easy

Introduction

• Semantic versioning pour avoir un standard sur la manière dont les montées de versions sont effectuées

• Semantic release pour gérer l’interaction entre les versions du répertoire de code, et les releases de l’application

• Git et une gestion des branches et du flow standardisée au sein d’un même répertoire

Présentation des outils

Semantic versioning

<valid semver> ::= <version core>
                 | <version core> "-" <pre-release>
                 | <version core> "+" <build>
                 | <version core> "-" <pre-release> "+" <build>

<version core> ::= <major> "." <minor> "." <patch>

• 1.4.3

• 63.0.0

• 2.0.0-alpha1

• 3.5.1+20231002

• 0.9.11-preview+pr193

• si la version corrige un bug, ou n’inclue pas de nouvelles fonctionnalités (par exemple une optimisation, ou une réorganisation du code), alors on monte la version de patch

• si la version inclue une nouvelle fonctionnalité, autant pour les utilisateurs qu’en interne de la base de code, alors on monte la version mineure

• si la version inclue des changements incompatibles avec la version précédente, alors on monte la version majeure

Semantic release

Git

• chore/<branch-name> : pour les changements qui ne s’intègrent pas dans les catégories d’au-dessus (perf, refactoring, etc).

• fix/<branch-name> : réparation d’un bogue

• feat/<branch-name> : ajout d’une nouvelle fonctionnalité

• nom de la fonctionnalité, description du bogue, etc

• identifiant d’un ticket sur un logiciel externe (Jira, etc)

• nom du développeur et identifiant d’une tâche, etc

• et bien d’autres possibilités

Mise en place

• Installation de Semantic release

• Configuration de Semantic release

• Mise-à-jour de la CI/CD pour tout y intégrer

Installation de Semantic release

npm install --save-dev semantic-release

# Requis dans tous les cas
npm install --save-dev @semantic-release/commit-analyzer @semantic-release/exec
# À adapter suivant la plateforme que vous utilisez
npm install --save-dev @semantic-release/gitlab

Configuration de Semantic release

branches:
	# N'activer que sur la branche 'main'
  - main


plugins:
	# Analyse des commits pour extraire le type et le nom des changements effectués
  - "@semantic-release/commit-analyzer"

	# Créer des nouveaux tags sur Gitlab
  - "@semantic-release/gitlab"

	# Créer un fichier contenant le nom de la nouvelle version à chaque release
	# /!\ il y a bien deux tirets d'affilée
  - - "@semantic-release/exec"
    - verifyReleaseCmd: "echo ${nextRelease.version} > .VERSION"

• Semantic release ne s’active que sur la branche main, en effet, sur les autres branches, il n’y a pas de release à créer puisque les changements n’ont lieu que sur des environnements de tests éphémères et instables

• configuration de trois plugins, un pour pouvoir lire et analyser le contenu des commits effectués entre chaque release, un pour pouvoir se connecter à Gitlab et créer et pousser de nouveaux tags, et enfin un dernier pour créer un fichier contenant le nom de la nouvelle version. Ce fichier sera utilisé dans les pipelines de CI/CD que nous décrirons après.

Configuration des pipelines de CI/CD

Nous prendrons ici comme exemple une pipeline Gitlab CI, mais le fonctionnement est le même sur Github Actions, Jenkins, Azure DevOps, et tous les autres outils de ce type.

• La première, dite de Pre-Release, va calculer la nouvelle version de l’application

• La seconde, dite de Release, va construire puis pousser la nouvelle version de l’application

Pre-Release:
  stage: pre-release
  image: node:18
  script:
    - |
      if [[ "$CI_COMMIT_BRANCH" = "main" ]]; then
        npm install
        npx semantic-release
        test -e ".VERSION" || exit 0
        echo "VERSION=v$(cat .VERSION)" >> build.env
      elif [[ "$CI_COMMIT_BRANCH" = "staging" ]]; then echo "VERSION=staging" >> build.env
      elif [[ "$CI_COMMIT_BRANCH" = "develop" ]]; then echo "VERSION=dev" >> build.env
      else false
      fi
  artifacts:
    reports:
      dotenv: build.env
  variables:
    GL_TOKEN: $GITLAB_PAT
  only:
    - develop
    - staging
    - main

Release:
  stage: release
  image: docker:latest
  dependencies:
    - Build
    - Pre-Release
  services:
    - docker:dind
  script:
    - test -z "$VERSION" && { echo "VERSION is not set or is empty - skipping release"; exit 0; }
	  # On suppose ici qu'un autre job s'occupe de constuire une image Docker $IMAGE
		- docker tag $IMAGE $REGISTRY/$IMAGE:$VERSION
    - docker push $REGISTRY/$IMAGE:$VERSION
  only:
    - develop
    - staging
    - main

Conclusion

• Travail local, test du code, puis envoi vers l’hébergeur Git

• Intégration continue via l’hébergeur, et calcul d’une nouvelle version suivant la branche courante et le nom des commits précédants

• Construction d’une nouvelle image Docker

• Délivrance continue gérée par ArgoCD