Skip to content

📦 Guide de Versioning - Yin Shi

Ce guide explique comment gérer les versions de l'application Yin Shi de manière cohérente entre tous les développeurs et toutes les plateformes.

📋 Format de version

MAJOR.MINOR.PATCH+BUILD

Exemple: 1.0.8+24

  • MAJOR (1) : Changements majeurs incompatibles (breaking changes)
  • MINOR (0) : Nouvelles fonctionnalités (rétrocompatible)
  • PATCH (8) : Corrections de bugs
  • BUILD (24) : Numéro de build (auto-incrémenté)

🚀 Workflow de versioning

Pour les développeurs

1. Corrections de bugs (PATCH)

# Incrémenter la version patch
./scripts/version-manager.sh patch

# Commit et push
git add pubspec.yaml
git commit -m "🐛 Fix: Description du bug corrigé"
git push

Exemple: 1.0.8 → 1.0.9

2. Nouvelles fonctionnalités (MINOR)

# Incrémenter la version minor
./scripts/version-manager.sh minor

# Commit et push
git add pubspec.yaml
git commit -m "✨ Feature: Description de la nouvelle fonctionnalité"
git push

Exemple: 1.0.9 → 1.1.0

3. Changements majeurs (MAJOR)

# Incrémenter la version major
./scripts/version-manager.sh major

# Commit et push
git add pubspec.yaml
git commit -m "💥 Breaking: Description du changement majeur"
git push

Exemple: 1.1.0 → 2.0.0

4. Vérifier la version actuelle

./scripts/version-manager.sh show

Pour GitHub Actions (Android)

Le build number est automatiquement incrémenté par le workflow GitHub Actions :

  1. Vous lancez le workflow
  2. Le workflow lit 1.0.8+23 dans pubspec.yaml
  3. Il incrémente automatiquement : 1.0.8+24
  4. Il build avec le nouveau numéro
  5. Il commit le nouveau numéro dans le repo

Résultat : Vous n'avez jamais à incrémenter manuellement le build number pour Android !

📊 Convention de versioning

Quand incrémenter MAJOR ?

  • Refonte complète de l'interface
  • Changement de base de données incompatible
  • Suppression de fonctionnalités majeures
  • Migration vers une nouvelle architecture

Fréquence: Rare (tous les ans ou plus)

Quand incrémenter MINOR ?

  • Ajout d'une nouvelle fonctionnalité
  • Amélioration significative d'une fonctionnalité existante
  • Ajout d'une nouvelle page/écran
  • Nouvelle intégration (nouveau service, nouvelle API)

Fréquence: Régulière (toutes les semaines/mois)

Quand incrémenter PATCH ?

  • Correction de bug
  • Amélioration de performance
  • Correction de texte/traduction
  • Petite amélioration UX

Fréquence: Très régulière (plusieurs fois par semaine)

Build number

  • Automatiquement incrémenté par CI/CD pour Android
  • Unique et toujours croissant
  • Ne jamais le modifier manuellement pour Android
  • Pour les autres plateformes, suivre la convention de la plateforme

🔄 Workflow multi-développeurs

Scénario 1 : Développement en parallèle

Développeur A travaille sur une fonctionnalité : 

git checkout -b feature/nouvelle-fonction
# Développement...
./scripts/version-manager.sh minor  # 1.0.8 → 1.1.0
git commit -m "✨ Feature: Nouvelle fonction"

Développeur B corrige un bug en même temps : 

git checkout -b fix/bug-xyz
# Correction...
./scripts/version-manager.sh patch  # 1.0.8 → 1.0.9
git commit -m "🐛 Fix: Correction bug XYZ"

Résolution : 1. Merger d'abord le fix (plus urgent) → Version 1.0.9 2. Développeur A rebase et adapte → Version 1.1.0 3. Pas de conflit de build number (auto-géré par CI/CD)

Scénario 2 : Release

Préparation d'une release :

  1. Finaliser les fonctionnalités 

    git checkout develop
git pull

  2. Incrémenter la version 

    # Pour une release avec nouvelles fonctionnalités
./scripts/version-manager.sh minor

# Pour une release de corrections uniquement
./scripts/version-manager.sh patch

  3. Mettre à jour les notes de version 

    # Éditer distribution/whatsnew/whatsnew-fr-FR
# Éditer distribution/whatsnew/whatsnew-en-US

  4. Commit et tag 

    git add pubspec.yaml distribution/whatsnew/
git commit -m "🚀 Release v1.1.0"
git tag v1.1.0
git push origin develop --tags

  5. Lancer le workflow GitHub Actions

  6. Le build number sera auto-incrémenté
  7. Le déploiement se fera automatiquement

🎯 Bonnes pratiques

✅ À FAIRE

  • ✅ Incrémenter la version avant de merger dans main/develop
  • ✅ Mettre à jour les notes de version (whatsnew) pour chaque release
  • ✅ Utiliser le script version-manager.sh pour éviter les erreurs
  • ✅ Commiter la version avec un message clair
  • ✅ Laisser le CI/CD gérer le build number pour Android
  • ✅ Synchroniser régulièrement (git pull) pour éviter les conflits

❌ À ÉVITER

  • ❌ Ne jamais modifier manuellement le build number pour Android
  • ❌ Ne pas oublier de commiter pubspec.yaml après incrémentation
  • ❌ Ne pas incrémenter la version dans plusieurs branches en parallèle
  • ❌ Ne pas oublier de mettre à jour les notes de version

⚔️ Gestion des conflits de version

Scénario : Deux développeurs incrémentent en parallèle

Développeur A : 

git checkout -b feature/A
./scripts/version-manager.sh minor  # 1.0.8 → 1.1.0
git commit -m "✨ Feature A"
git push

Développeur B en même temps : 

git checkout -b feature/B
./scripts/version-manager.sh minor  # 1.0.8 → 1.1.0 (conflit!)
git commit -m "✨ Feature B"
git push

✅ Résolution : Premier arrivé, premier servi

Étape 1 : Le développeur A merge en premier 

git checkout main
git merge feature/A  # ✅ 1.1.0 sur main
git push

Étape 2 : Le développeur B doit s'adapter 

# 1. Vérifier les conflits potentiels
./scripts/check-version-conflict.sh

# 2. Pull les changements
git checkout main
git pull

# 3. Rebaser
git checkout feature/B
git rebase main
# CONFLIT sur pubspec.yaml !

# 4. Résoudre : incrémenter à nouveau
./scripts/version-manager.sh minor  # 1.1.0 → 1.2.0
git add pubspec.yaml
git rebase --continue
git push --force-with-lease

🛡️ Stratégies de prévention

Stratégie 1 : Communication (Recommandé)

Communiquez avant d'incrémenter :

💬 Slack/Discord :
Dev A: "Je merge feature A, passage en 1.1.0"
Dev B: "OK, j'attends ⏸️"

[Après merge de A]
Dev B: git pull && ./scripts/version-manager.sh minor # 1.1.0 → 1.2.0

Stratégie 2 : Incrémenter au moment du merge

Ne pas incrémenter dans les branches, mais au moment du merge :

# Dans la feature branch : PAS d'incrémentation
git checkout -b feature/ma-fonction
# ... développement ...
git commit -m "feat: ma fonction"

# Avant de merger : Incrémenter maintenant
git checkout main
git pull
./scripts/check-version-conflict.sh  # Vérifier
./scripts/version-manager.sh minor
git add pubspec.yaml
git commit -m "🔢 Bump version for release"
git merge feature/ma-fonction --no-ff
git push

Stratégie 3 : Releases coordonnées

Regrouper plusieurs features dans une release :

# Phase de développement (1 semaine)
Dev A: feature/A (pas de version change)
Dev B: feature/B (pas de version change)
Dev A: feature/C (pas de version change)

# Fin de sprint : Release coordonnée
git checkout main
git merge feature/A
git merge feature/B  
git merge feature/C
./scripts/version-manager.sh minor  # Une seule fois: 1.1.0
git push

🔍 Détection des conflits

Avant d'incrémenter, vérifiez :

./scripts/check-version-conflict.sh

Ce script vous dira : - ✅ Version locale vs version sur origin/main - ⚠️ S'il y a des conflits potentiels - 📊 Commits non pushés/pullés

🛠️ Outils

Script check-version-conflict.sh

# Vérifier les conflits potentiels avant d'incrémenter
./scripts/check-version-conflict.sh

Exemple de sortie : 

🔍 Vérification des conflits de version
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📦 Version locale: 1.0.8+24
🌐 Version sur origin/main: 1.1.0+25

⚠️  Les versions sont différentes !
❌ ATTENTION: Conflit de version sémantique !

Recommandations:
1. git pull origin main
2. Résoudre les conflits sur pubspec.yaml
3. Incrémenter à nouveau si nécessaire

Script version-manager.sh

# Afficher la version actuelle
./scripts/version-manager.sh show

# Incrémenter le build (manuel, rarement nécessaire)
./scripts/version-manager.sh build

# Incrémenter patch (bug fixes)
./scripts/version-manager.sh patch

# Incrémenter minor (nouvelles fonctionnalités)
./scripts/version-manager.sh minor

# Incrémenter major (breaking changes)
./scripts/version-manager.sh major

# Définir une version spécifique
./scripts/version-manager.sh set 2.0.0

# Aide
./scripts/version-manager.sh help

📱 Spécificités par plateforme

Android

  • ✅ Build number auto-incrémenté par GitHub Actions
  • Format version dans pubspec.yaml: 1.0.8+24
  • Version code (24) doit être unique et croissant
  • Version name (1.0.8) visible par les utilisateurs

iOS

  • Format similaire à Android
  • Géré via pubspec.yaml
  • Build number peut être synchronisé avec Android

Windows / Linux / macOS

  • Format similaire
  • Géré via pubspec.yaml
  • Pas de contrainte stricte sur le build number

Web (PWA)

  • Version visible dans le manifest
  • Peut suivre la même version que mobile

📞 En cas de problème

"Version code already exists" sur Play Store

Cause: Le build number existe déjà sur le Play Store

Solution: Le workflow l'incrémente automatiquement maintenant. Si le problème persiste : 

./scripts/version-manager.sh build
git add pubspec.yaml
git commit -m "🔢 Increment build number"
git push

Conflit de version entre développeurs

Cause: Deux développeurs ont incrémenté la version en parallèle

Solution: 1. Le premier merge gagne 2. Le second doit rebaser et adapter sa version 3. Coordination via Slack/Discord avant d'incrémenter

Build number désynchronisé

Cause: Modification manuelle du build number

Solution: Laisser le CI/CD auto-incrémenter. Si vraiment nécessaire : 

# Récupérer le dernier build number du Play Store
# L'ajouter +1 dans pubspec.yaml
./scripts/version-manager.sh set 1.0.8 25

🎉 Résumé

  • Version MAJOR.MINOR.PATCH : Géré manuellement par les développeurs
  • Build number : Auto-incrémenté par CI/CD pour Android
  • Script version-manager.sh : Facilite la gestion manuelle
  • Workflow GitHub Actions : Gère automatiquement le build number Android

Pour déployer : Il suffit de lancer le workflow GitHub Actions. Le reste est automatique ! 🚀

📝 Gestion des notes de version (WhatsNew)

Structure des fichiers WhatsNew

Le dossier distribution/whatsnew/ contient deux types de fichiers :

1. Fichiers de traduction multilingue (whatsnew-xx)

  • whatsnew-fr : Version française des nouveautés
  • whatsnew-en : Version anglaise
  • whatsnew-es : Version espagnole
  • whatsnew-de : Version allemande
  • whatsnew-ar : Version arabe

Ces fichiers sont utilisés par l'application pour afficher les nouveautés aux clients selon leur langue. Ils doivent toujours contenir les informations de la dernière version publiée.

2. Fichiers de suivi par version (whatsnew-x.x.x)

  • whatsnew-1.0.21, whatsnew-1.0.22, whatsnew-1.0.23, etc.

Ces fichiers permettent d'avoir un historique complet de ce qui a été ajouté à chaque version. Ils servent de référence pour le suivi des évolutions au fur et à mesure du développement.

Workflow de mise à jour

  1. Pendant le développement : Mettre à jour whatsnew-x.x.x (où x.x.x est la prochaine version) pour suivre les changements en cours
  2. Au moment de la release :
  3. Finaliser le contenu de whatsnew-x.x.x
  4. Copier ce contenu vers tous les fichiers whatsnew-xx (traductions)
  5. Les fichiers de traduction seront utilisés par l'application pour afficher les nouveautés aux utilisateurs

Exemple de workflow

# Début du développement de la version 1.0.24
# Éditer distribution/whatsnew/whatsnew-1.0.24 pour suivre les changements

# Au moment de la release
cp distribution/whatsnew/whatsnew-1.0.24 distribution/whatsnew/whatsnew-fr
# (puis adapter/traduire pour les autres langues)

# Commit des changements
git add distribution/whatsnew/
git commit -m "📝 Mise à jour des notes de version v1.0.24"

Important : Les fichiers whatsnew-xx doivent être mis à jour à chaque changement de version car ils sont lus par l'application pour informer les clients des nouveautés.