Workflow GitFlow UI

Strategie GitFlow pour les interfaces utilisateur (UI) du projet MyTelevision, couvrant les applications Web, Mobile et Smart TV qui consomment l'API backend.

Applications Concernees

Application	Stack	Repository
Web App	Next.js / React	`mytelevision-web`
Mobile iOS	React Native / Swift	`mytelevision-mobile`
Mobile Android	React Native / Kotlin	`mytelevision-mobile`
Smart TV	React / Tizen / webOS	`mytelevision-tv`
Admin Dashboard	Next.js / React	`mytelevision-admin`

Objectifs

Synchronisation API/UI : Les interfaces consomment toujours une version compatible de l'API
Validation visuelle : Les equipes produit et design valident l'UX/UI avant la production
Tests d'integration : Verification de la compatibilite API sur l'environnement preview
Deploiements coordonnes : Les releases UI sont alignees avec les releases API
Retro-compatibilite : Support des versions API N et N-1 pendant les transitions

Modele de Branches

Hierarchie des Branches

Branche	Type	Objectif	Protegee	API Cible
`main`	Production	Code pret pour la production	Oui	`api.mytelevision.com`
`develop`	Integration	Integration du developpement	Oui	`dev.api.mytelevision.com`
`preview`	Validation	Validation produit/UX/UI	Oui	`preview.api.mytelevision.com`
`release/*`	Pre-production	Durcissement avant release	Non	`staging.api.mytelevision.com`
`feature/*`	Developpement	Nouvelles fonctionnalites	Non	`dev.api.mytelevision.com`
`bugfix/*`	Developpement	Corrections de bugs	Non	`dev.api.mytelevision.com`
`ui/*`	Developpement	Changements UI purs	Non	Mock/Dev
`hotfix/*`	Urgence	Corrections de production	Non	`api.mytelevision.com`

Convention de Nommage

# Branches de fonctionnalite (avec integration API)
feature/web/<nom-fonctionnalite>
feature/mobile/<nom-fonctionnalite>
feature/tv/<nom-fonctionnalite>
feature/admin/<nom-fonctionnalite>

# Branches UI pures (sans nouvelle integration API)
ui/web/<nom-changement>
ui/mobile/<nom-changement>
ui/tv/<nom-changement>

# Branches de correction
bugfix/web/<nom-correction>
bugfix/mobile/<nom-correction>

# Branches de release et hotfix
release/vX.Y.Z
hotfix/vX.Y.Z-<description>

# Exemples concrets
feature/web/page-authentification
feature/mobile/lecteur-video
ui/web/refonte-header
bugfix/web/correction-scroll-infini
hotfix/v2.5.1-correction-crash-ios

Duree de Vie des Branches

Branche	Duree de Vie
`main`	Permanente
`develop`	Permanente
`preview`	Permanente
`feature/*`	Max 2 semaines
`ui/*`	Max 1 semaine
`bugfix/*`	Max 1 semaine
`release/*`	Jusqu'au merge vers main
`hotfix/*`	Jusqu'au merge vers main

Versionnement Semantique

MAJEUR (X.0.0) : Changements d'UI majeurs, refonte complete
MINEUR (0.X.0) : Nouvelles fonctionnalites, nouveaux ecrans
CORRECTIF (0.0.X) : Corrections de bugs, ajustements visuels

Branche Preview -- Role Detaille

La branche preview pour les projets UI sert de validation visuelle et fonctionnelle avant la release, connectee a l'environnement preview de l'API.

Cas d'Usage

Cas d'Usage	Description
Validation UX/UI	L'equipe design valide les maquettes implementees
Tests d'Integration API	Verification de la compatibilite avec l'API preview
Revue Produit	Les Product Owners testent les parcours utilisateur
Demos Clients	Presentations sur un environnement stable
Tests Multi-Plateformes	Validation sur differents appareils/navigateurs
A/B Testing	Tests de variantes avant deploiement

Responsabilites

Role	Responsabilite
Tech Lead Frontend	Approuve les merges vers preview
UI/UX Designer	Valide la conformite aux maquettes
Product Owner	Valide les parcours utilisateur
QA Lead	Signe la qualite fonctionnelle
DevOps	Maintient l'environnement preview

Cycle de Vie de la Branche Preview

Synchronisation Reguliere

# Etape 1 : S'assurer que develop est a jour
git checkout develop
git pull origin develop

# Etape 2 : Basculer vers preview et synchroniser
git checkout preview
git pull origin preview

# Etape 3 : Merger develop dans preview
git merge develop --no-ff -m "chore(preview): synchronisation avec develop $(date +%Y-%m-%d)

Fonctionnalites incluses:
- feat(web): page d'authentification
- feat(mobile): lecteur video
- ui(web): refonte header"

# Etape 4 : Pousser vers le depot distant
git push origin preview

Coordination avec l'API

Regle Imperiale

Ne jamais deployer l'UI preview si l'API preview n'est pas synchronisee et fonctionnelle.

# Toujours verifier la compatibilite API avant de synchroniser

# Etape 1 : Verifier le statut de l'API preview
curl -s https://preview.api.mytelevision.com/health | jq .

# Etape 2 : Verifier la version de l'API
curl -s https://preview.api.mytelevision.com/api/v2/version | jq .

# Etape 3 : Synchroniser uniquement si l'API est prete
git checkout preview
git merge develop --no-ff -m "chore(preview): sync avec develop - API v2.5.0 compatible"

Transitions d'Etat

+------------------------------------------------------------------+
|                    ETATS DE LA BRANCHE PREVIEW UI                 |
+------------------------------------------------------------------+
|                                                                   |
|   SYNCHRO --> VALIDATION --> APPROUVE --> EN RELEASE              |
|      |            |             |              |                  |
|      v            v             v              v                  |
|   Merge de    Tests &       Pret pour      Release/*             |
|   develop     Revue UX      release        creee                 |
|                                                                   |
|   BLOQUE <-- API preview non disponible                          |
|      |                                                            |
|      v                                                            |
|   Attendre que l'API soit synchronisee                           |
|                                                                   |
|   REJETE <-- Problemes UX/UI trouves                             |
|      |                                                            |
|      v                                                            |
|   Retour vers develop pour corrections                           |
+------------------------------------------------------------------+

Gestion des Feature Flags

src/config/features.ts
export const FEATURE_FLAGS = {
  preview: {
    NEW_VIDEO_PLAYER: true,
    DARK_MODE: true,
    VOICE_SEARCH: false, // Pas encore pret
  },
  production: {
    NEW_VIDEO_PLAYER: false,
    DARK_MODE: false,
    VOICE_SEARCH: false,
  },
};

Regles de Merge

Chemins Autorises

Source	Cible	Autorise	Strategie	Approbations
`feature/*`	`develop`	Oui	Squash	1 dev + 1 designer
`ui/*`	`develop`	Oui	Squash	1 dev + 1 designer
`bugfix/*`	`develop`	Oui	Squash	1 developpeur
`develop`	`preview`	Oui	Merge commit	Tech Lead Frontend
`preview`	`release/*`	Oui	Merge commit	Tech Lead + Produit + Design
`release/*`	`main`	Oui	No-ff	2 reviewers
`release/*`	`develop`	Oui	No-ff	1 developpeur
`hotfix/*`	`main`	Oui	No-ff	2 reviewers
`hotfix/*`	`develop`	Oui	No-ff	1 developpeur

Chemins Interdits

Source	Cible	Raison
`feature/*`	`preview`	Doit passer par develop d'abord
`ui/*`	`preview`	Doit passer par develop d'abord
`feature/*`	`main`	Jamais directement vers la production
`hotfix/*`	`preview`	Les hotfixes contournent preview
`develop`	`main`	Doit passer par preview et release
`preview`	`main`	Doit passer par release

Commandes Git

# Merge squash (feature vers develop)
git checkout develop
git merge --squash feature/web/page-authentification
git commit -m "feat(web): implementation page authentification

- Formulaire de connexion
- Integration API /auth/login
- Gestion des erreurs
- Tests unitaires

Closes #123"

# Merge commit (develop vers preview)
git checkout preview
git merge develop --no-ff -m "chore(preview): sync avec develop

Inclut:
- feat(web): page authentification
- ui(web): refonte header
- bugfix(mobile): scroll infini

API compatible: v2.5.0"

Protection des Branches

Branche `main`

Regles de Protection:
  - Exiger les revues de pull request: 2
  - Rejeter les revues obsoletes: true
  - Exiger les verifications de statut:
      - lint
      - test
      - build
      - e2e-tests
      - lighthouse
  - Exiger que les branches soient a jour: true
  - Inclure les administrateurs: true
  - Autoriser les force push: false

Branche `develop`

Regles de Protection:
  - Exiger les revues de pull request: 1 (dev) + 1 (design pour feature/ui)
  - Exiger les verifications de statut:
      - lint
      - test
      - build
      - visual-regression
  - Exiger que les branches soient a jour: true
  - Autoriser les force push: false

Branche `preview`

Regles de Protection:
  - Exiger les revues de pull request: 1 (Tech Lead Frontend)
  - Exiger les verifications de statut:
      - lint
      - test
      - build
      - e2e-tests
      - api-integration-check
  - Restreindre qui peut pousser:
      - Tech Leads Frontend
      - DevOps
  - Autoriser les force push: false

CI/CD et Environnements

Correspondance des Environnements

Branche UI	Environnement	URL UI	API Cible
`develop`	Developpement	`dev.mytelevision.com`	`dev.api.mytelevision.com`
`preview`	Preview	`preview.mytelevision.com`	`preview.api.mytelevision.com`
`release/*`	Staging	`staging.mytelevision.com`	`staging.api.mytelevision.com`
`main`	Production	`mytelevision.com`	`api.mytelevision.com`

Variables d'Environnement

Variable	Dev	Preview	Staging	Prod
`NEXT_PUBLIC_API_URL`	dev.api...	preview.api...	staging.api...	api...
`NEXT_PUBLIC_ENV`	development	preview	staging	production
`ENABLE_ANALYTICS`	false	true	true	true
`ENABLE_ERROR_REPORTING`	false	true	true	true
`DEBUG_MODE`	true	true	false	false

Tags Docker

Branche	Format de Tag	Exemple
`develop`	`:develop`, `:develop-sha-<short>`	`:develop-sha-abc1234`
`preview`	`:preview`, `:preview-sha-<short>`	`:preview-sha-def5678`
`release/*`	`:staging`, `:v3.0.0-rc.1`	`:v3.0.0-rc.1`
`main`	`:latest`, `:v3.0.0`	`:v3.0.0`

Integration API

Matrice de Compatibilite

+------------------------------------------------------------------+
|           MATRICE DE COMPATIBILITE UI <-> API                     |
+------------------------------------------------------------------+
|                                                                   |
|   UI Branch        ->    API Environment                         |
|   ---------              ---------------                         |
|                                                                   |
|   develop          ->    dev.api.mytelevision.com               |
|   preview          ->    preview.api.mytelevision.com           |
|   release/*        ->    staging.api.mytelevision.com           |
|   main             ->    api.mytelevision.com                   |
|                                                                   |
+------------------------------------------------------------------+

Workflow de Synchronisation UI/API

Gestion des Versions API

src/services/api/version.ts
interface ApiVersionConfig {
  minVersion: string;
  recommendedVersion: string;
  deprecatedEndpoints: string[];
}

const API_VERSION_CONFIG: ApiVersionConfig = {
  minVersion: '2.4.0',
  recommendedVersion: '2.5.0',
  deprecatedEndpoints: [
    '/api/v1/users', // Utiliser /api/v2/users
    '/api/v1/movies', // Utiliser /api/v2/movies
  ],
};

export async function checkApiCompatibility(): Promise<boolean> {
  try {
    const response = await fetch(`${API_BASE_URL}/api/v2/version`);
    const { version } = await response.json();

    if (compareVersions(version, API_VERSION_CONFIG.minVersion) < 0) {
      console.error(
        `API version ${version} is below minimum ${API_VERSION_CONFIG.minVersion}`,
      );
      return false;
    }

    return true;
  } catch (error) {
    console.error('Failed to check API compatibility', error);
    return false;
  }
}

Diagramme GitFlow

Diagramme de Flux UI/API

Cas d'Usage Concrets

Nouvelle Page avec Integration API

# Verifier que l'API develop a les endpoints
curl -s https://dev.api.mytelevision.com/api/v2/auth/login -X POST \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]","password":"test"}' | jq .

# Partir de develop
git checkout develop && git pull origin develop

# Creer la branche feature
git checkout -b feature/web/page-authentification

# Developper et commiter
git commit -m "feat(web): ajout formulaire de connexion"
git commit -m "feat(web): integration API auth/login"
git commit -m "test(web): tests unitaires page authentification"

# Garder a jour et pousser
git fetch origin && git rebase origin/develop
git push -u origin feature/web/page-authentification

Changement UI Pur

# Partir de develop
git checkout develop && git pull origin develop

# Creer la branche UI
git checkout -b ui/web/refonte-header

# Implementer et commiter
git commit -m "ui(web): nouveau layout header desktop"
git commit -m "ui(web): header responsive mobile/tablet"
git commit -m "test(web): tests visuels header"

# Capturer les screenshots avant/apres
npm run test:visual:update

# Pousser et creer la PR avec screenshots
git push -u origin ui/web/refonte-header

Synchronisation UI Preview

# Verifier que l'API preview est prete
curl -s https://preview.api.mytelevision.com/health | jq .

# S'assurer que develop est stable
git checkout develop && git pull origin develop

# Synchroniser preview
git checkout preview && git pull origin preview
git merge develop --no-ff -m "chore(preview): sync avec develop - Sprint 24

Fonctionnalites incluses:
- feat(web): page authentification
- feat(mobile): lecteur video ameliore
- ui(web): refonte header

API compatible: v2.5.0"

git push origin preview

Release Coordonnee UI/API

# Verifier la compatibilite avec staging API
curl -s https://staging.api.mytelevision.com/health | jq .

# Creer la release depuis preview
git checkout preview && git pull origin preview
git checkout -b release/v3.1.0

# Configurer pour staging
npm version minor --no-git-tag-version
git commit -m "chore(release): preparation v3.1.0"
git push -u origin release/v3.1.0

# Apres validation, merger vers main
git checkout main && git pull origin main
git merge release/v3.1.0 --no-ff -m "chore(release): v3.1.0"
git tag -a v3.1.0 -m "Release v3.1.0 - Coordonnee avec API v2.5.0"
git push origin main --tags

# Retro-merger vers develop
git checkout develop
git merge release/v3.1.0 --no-ff
git push origin develop

Anti-patterns

Violations Critiques -- Ne Jamais Faire

Anti-pattern	Approche Correcte
Deployer UI preview sans verifier API	Toujours verifier la compatibilite API d'abord
Hardcoder les URLs d'API	Utiliser des variables d'environnement
Ignorer les erreurs API	Implementer une gestion d'erreurs robuste
Feature branch directe vers preview	Feature -> develop -> preview
Deployer sans screenshots dans la PR	Toujours inclure des captures d'ecran
Ne pas supporter les versions API N-1	Supporter 2 versions pendant la transition

Erreurs d'Integration API

// FAUX : URL hardcodee
const API_URL = 'https://api.mytelevision.com';

// CORRECT : Variable d'environnement
const API_URL = process.env.NEXT_PUBLIC_API_URL;

// FAUX : Pas de gestion d'erreur
const response = await fetch(`${API_URL}/movies`);
const data = await response.json();

// CORRECT : Gestion d'erreur complete
try {
  const response = await fetch(`${API_URL}/movies`);
  if (!response.ok) {
    throw new ApiError(response.status, await response.text());
  }
  const data = await response.json();
  return data;
} catch (error) {
  if (error instanceof ApiError) {
    handleApiError(error);
  }
  return fallbackData;
}

Carte de Reference Rapide

Workflow Quotidien (Feature avec API)

curl -s https://dev.api.mytelevision.com/health | jq .
git checkout develop && git pull && git checkout -b feature/web/ma-feature
git add . && git commit -m "feat(web): description"
git push -u origin feature/web/ma-feature

Workflow Quotidien (UI Pure)

git checkout develop && git pull && git checkout -b ui/web/mon-changement
git add . && git commit -m "ui(web): description"
npm run test:visual:update
git push -u origin ui/web/mon-changement

Sync Preview (Tech Lead)

curl -s https://preview.api.mytelevision.com/health | jq .
git checkout develop && git pull
git checkout preview && git pull
git merge develop --no-ff -m "chore(preview): sync - API vX.Y.Z"
git push origin preview

Creer une Release

curl -s https://staging.api.mytelevision.com/health | jq .
git checkout preview && git pull
git checkout -b release/vX.Y.Z
npm version minor --no-git-tag-version
git add . && git commit -m "chore(release): vX.Y.Z"
git push -u origin release/vX.Y.Z

Applications Concernees​

Objectifs​

Modele de Branches​

Hierarchie des Branches​

Convention de Nommage​

Duree de Vie des Branches​

Versionnement Semantique​

Branche Preview -- Role Detaille​

Cas d'Usage​

Responsabilites​

Cycle de Vie de la Branche Preview​

Synchronisation Reguliere​

Coordination avec l'API​

Transitions d'Etat​

Gestion des Feature Flags​

Regles de Merge​

Chemins Autorises​

Chemins Interdits​

Commandes Git​

Protection des Branches​

Branche main​

Branche develop​

Branche preview​

CI/CD et Environnements​

Correspondance des Environnements​

Variables d'Environnement​

Tags Docker​

Integration API​

Matrice de Compatibilite​

Workflow de Synchronisation UI/API​

Gestion des Versions API​

Diagramme GitFlow​

Diagramme de Flux UI/API​

Cas d'Usage Concrets​

Nouvelle Page avec Integration API​

Changement UI Pur​

Synchronisation UI Preview​

Release Coordonnee UI/API​

Anti-patterns​

Erreurs d'Integration API​

Carte de Reference Rapide​

Workflow Quotidien (Feature avec API)​

Workflow Quotidien (UI Pure)​

Sync Preview (Tech Lead)​

Creer une Release​