Gestion de la production - betagouv/pix GitHub Wiki

Gestion de production

Numérotage des versions

Semantic Versioning 2.0.0

Le numérotage des versions de l'application PIX respecte le formalisme Semantic Versioning 2.0.0.

Une version du projet se présente donc sous la forme suivante : MAJOR.MINOR.PATCH, ex : "1.2.1".

Dans le cas de PIX :

  • la valeur MAJOR est incrémentée à chaque livraison de fin d'itération
  • la valeur MINOR est incrémentée lorsqu'une livraison a lieu en cours d'itération et comporte un ajout de fonctionnalité [FEATURE]
  • la valeur PATCH est incrémentée lorsqu'une livraison a lieu en cours d'itération et ne contient que des corrections de bugs [BUGFIX], des développements de nettoyage du code [CLEANUP] ou de la documentation [DOC]

Exemple

Par exemple, la version 1.0.0 correspond à la version livrée à la fin de l'itération #1.

Peu de temps après, au début de l'itération #2, nous nous sommes rendus compte qu'il fallait très rapidement livrer la fonctionnalité "Responsive Web Design".

Tous ensemble, nous avons estimé que cette fonctionnalité ne pouvait pas attendre la fin de l'itération (une itération sur PIX équivalent à 2 semaines) et la livraison de la version 2.0.0.

Nous avons alors livré en production la version 1.1.0.

Il s'avère que suite à cette livraison, nous avons introduit une régression, à corriger de toute urgence (l'inscription à la communauté des bêta-testeurs de PIX).

Nous avons alors livré en production la version 1.1.1.

La fin de l'itération #2 s'est déroulée sans encombre ni urgence.

Nous avons alors livré en production la version 2.0.0.

Suivi des modifications

Changelog

Toutes les modifications de code envoyées en production sont listées dans le fichier CHANGELOG.md.

Chaque version est indiquée selon le formalisme suivant : VERSION (dd/mm/yyyy), ex : "1.1.1 (24/11/2017)".

Le détail d'une version reprend la liste des (lot de) modifications embarquées dans la release.

Chaque modification est indiquée selon le formalisme suivant : [#XYZ] [TAG] DESCRIPTION, ex : "#272 [FEATURE] Gestion du Responsive Web Design.".

Dans le cas de PIX :

  • XYZ est l'identifiant de la Pull Request portant la modification
  • TAG est l'une (et une seule) des étiquettes supportée dans le cadre du projet PIX (cf. section suivante)
  • DESCRIPTION est un texte court en français, commençant par une majuscule et finissant par un point.

Tags

Les tags autorisés sont les suivants :

  • FEATURE quand la modification du code porte sur l'ajout, l'extension ou la modification d'une fonctionnalité existante
  • BUGFIX quand la modification porte sur une correction de bug
  • DOC quand la modification porte sur l'ajout ou la mise à jour de la documentation
  • CLEANUP quand la modification porte sur du remaniement de code
  • INFRA quand la modification porte sur du code technique ayant trait à l'infrastructure, l'architecture ou le workflow de développement

Procédure de livraison & déploiement en production

Prérequis

Pour pouvoir livrer en production, vous devez au préalable :

  • disposer des droits d'écriture sur le repository GitHub SGMAP/pix-live
  • avoir autorisé votre clé SSH publique sur le serveur PIX
  • avoir déclaré votre clé SSH publique dans l'application Dokku (qui sur le serveur PIX) qui gère le parc applicatif PIX
  • être situé à la racine du projet
  • être positionné sur la branche master à jour
  • avoir les sources de la branche gh-pages à jour

Instructions

La procédure de livraison & déploiement en production est faite pour être simple, rapide et sécurisée.

Elle se résume à l'instruction make deploy-production exécutée depuis la racine du projet, sur la branche master (à jour) :

Exemple :

$ pwd
/Works/SGMAP/pix
 
$ git branch
  123-story-a
  456-story-b
  dev
  gh-pages
* master
 
$ git status
On branch master
Your branch is up-to-date with 'origin/master'.
nothing to commit, working directory clean
 
$ make deploy-production
-----> deploy...
-----> deploy...
-----> deploy...
=====> DONE!

Gestion des branches

Nous considérons 4 types de branche :

  • master (unique) contient exactement le code déployé en production
  • dev (unique) contient le code validé (lors des revues de code) éligible pour la production
  • gh-pages (unique) contient le code du module PIX-Live pour les différents environnements ou review apps
  • 123-xyz (autant que nécessaire) contient le code modifié propre à une story ou tâche technique

Remarque : la branche master est déclarée sur GitHub comme branche protégée.

Scénarios possibles

Livraison de fin d'itération

Ce cas se présente chaque mercredi après-midi de fin d'itération.

1/ Préparer la livraison

  1. Se placer à la racine du répertoire projet
  2. Se positionner sur la branche dev
  3. Récupérer les dernières sources (attention de ne pas avoir de modifications locales en cours)
  4. Vérifier le numéro de version dans api/package.json et live/package.json
  5. Mettre à jour et commiter/pousser le fichier CHANGELOG.md (cf. ci-dessus)
  6. Se positionner sur la branche master
  7. Merger dev sur master et pousser
  8. Créer et pousser le tag Git de la forme MAJOR.0.0

2/ Livrer et déployer

  1. Exécuter la procédure de livraison & déploiement (cf. ci-dessus)
  2. Vérifier que l'application est opérationnelle en production

3/ Préparer la prochaine version

  1. Se positionner sur la branche dev
  2. Incrémenter le numéro de version dans api/package.json et live/package.json
  3. Commiter/pousser directement sur dev

Exemple de livraison de l'application pour l'itération #2 en lignes de commande :

# 1/ Préparer la livraison
# ------------------------
 
$ cd /Works/SGMAP/pix # positionnement dans le répertoire racine
$ git fetch --all # récupération de toutes les branches
$ git checkout dev # positionnement sur la branche 'dev'
$ git status # vérification des éventuelles modifications locales en cours
$ git pull # récupération des dernières sources
$ cat api/package.json # vérification du numéro de version
$ cat live/package.json # vérification du numéro de version
$ vi CHANGELOG.md # mise à jour du changelog
$ git add CHANGELOG.md & git commit -m "DOC : Update CHANGELOG" # ajout et enregistrement des modifications du changelog
$ git push origin dev # propagation de la modification de 'dev' sur GitHub
$ git checkout master # positionnement sur la branche 'master'
$ git pull # récupération des dernières sources
$ git merge dev # report des modifications contenues sur la branche 'dev' 
$ git push origin master #  propagation de la modification de 'master' sur GitHub
$ git tag -a 2.0.0 -m "Release 2.0.0" # création du tag de la version 2.0.0
$ git push origin 2.0.0 # propagation du tag sur GitHub
 
# 2/ Livrer et déployer
# --------------------
 
$ make deploy-production # livraison et déploiement en production
$ curl https://pix.beta.gouv.fr # vérification de PIX-Live
$ curl https://pix.beta.gouv.fr/api/courses # vérification de PIX-API
 
# 3/ Préparer la prochaine version
# --------------------------------
 
$ git checkout dev # positionnement sur la branche 'dev'
$ vi api/package.json # incrémenter le numéro de version MAJOR (ici 3.0.0)
$ vi live/package.json # incrémenter numéro de version MAJOR (ici 3.0.0)
$ git add api/package.json live/package.json & git commit -m "DOC : Update version to 3.0.0" # ajout et enregistrement des modifications de version
$ git push origin dev # propagation de la modification de 'dev' sur GitHub

Livraison d'un bug ou d'une fonctionnalité bloquant(e) ou critique en cours d'itération

Ce cas se présente quand une version livrée en production présente un bug (hotfix) ou un défaut (de fonctionnalité) bloquant ou suffisamment critique pour nécessiter un patch ou une amélioration rapidement en production.

1/ Créer la branche de hotfix

  1. Se placer à la racine du répertoire projet
  2. Récupérer la liste des tags
  3. Tirer une nouvelle branche depuis le tag de la version à corriger, ex : dans le cas où la version en production est la 2.0.0, alors on tire une branche hotfix-2.0.1
  4. Mettre à jour le numéro de version dans api/package.json et live/package.json
  5. Commiter/pousser directement sur la branche
  6. Ouvrir la PR associée dans GitHub (pour récupérer son ID et pouvoir le mettre dans le changelog)

2/ Modifier le code

  1. Apporter les modifications en rapport avec la feature / le bug et commiter/pousser
  2. Mettre à jour et commiter/pousser le fichier CHANGELOG.md (cf. ci-dessus)
  3. Valider la PR

3/ Préparer la livraison

  1. Une fois la PR validée, se placer sur master
  2. Récupérer les dernières sources
  3. Merger la branche de hotfix sur master et pousser
  4. Créer et pousser le tag Git de la forme MAJOR.0.0

4/ Livrer et déployer

  1. Exécuter la procédure de livraison & déploiement (cf. ci-dessus)
  2. Vérifier que l'application est opérationnelle en production

5/ Reporter le hotfix sur la branche de dev

  1. Se placer sur la branche dev
  2. Merger la branche de hotfix sur dev et pousser

Livraison d'un lot de modifications en cours d'itération

Ce cas devrait rester exceptionnel, par exemple suite à une mise en production volumineuse (ex : nombreuses stories) potentiellement cassante (ex : incrémentation des APIs de PIX-API, changement et/ou migration d'infra ou d'archi).

Dans ce cas, la procédure est similaire à la livraison d'un bug / fonctionnalité en cours d'itération, à la différence, que chaque feature fait l'objet d'une nouvelle branche tirée depuis la branche hotfix-2.0.1 (dans le cas par exemple d'un hotfix sur la version 2.0.0).