Skip to main content

Principes de Développement - Projet Portail Web CAM

Ce document établit les principes et les bonnes pratiques que chaque développeur doit suivre pour contribuer au projet de refonte du portail web du Crédit Agricole Mutuel. L'adhésion à ces principes est essentielle pour garantir la qualité, la cohérence, la maintenabilité et la sécurité de l'application.

1. Suivre la "Drupal Way"​

Notre projet est basé sur Drupal 11. Nous devons capitaliser sur sa robustesse et son écosystème.

  • Ne jamais hacker le cœur : Aucune modification ne doit être apportée aux fichiers du Core de Drupal ou des modules contribués.
  • Utiliser les APIs : Privilégier systématiquement l'utilisation des APIs de Drupal (Form API, Render API, Entity API, etc.) pour interagir avec le système.
  • Favoriser les modules contribués : Avant de développer une fonctionnalité sur mesure, rechercher si un module contribué, stable et reconnu par la communauté, ne répond pas déjà au besoin.

2. Séparation Stricte des Responsabilités (Logique vs. Présentation)​

C'est le principe le plus important pour la maintenabilité de notre thème.

  • Les templates Twig doivent rester "stupides" : Un fichier .html.twig ne doit se concentrer que sur la présentation (structure HTML, classes CSS, affichage des variables). Il ne doit contenir aucune logique métier complexe.
  • La logique appartient au PHP : Toute préparation, formatage ou calcul de données doit être effectué en amont, dans les fonctions de prétraitement (hook_preprocess_*) du fichier cam_theme.theme.

Exemple concret :

❌ MAUVAIS (logique dans Twig) :

{# templates/node--offre-emploi.html.twig #}
<div class="date">
  Poste à pourvoir le : {{ node.field_date_prise_poste.value|date("l d F Y", "Europe/Paris") }}
</div>

✅ BON (logique dans PHP, affichage simple dans Twig) :

  • Préparation dans cam_theme.theme :
        /**
         * Implements hook_preprocess_node__offre_emploi().
         */
        function cam_theme_preprocess_node__offre_emploi(&$variables) {
          if (!$variables['node']->field_date_prise_poste->isEmpty()) {
            $date_formatter = \Drupal::service('date.formatter');
            $timestamp = $variables['node']->field_date_prise_poste->date->getTimestamp();
            $variables['date_formatee'] = $date_formatter->format($timestamp, 'custom', 'l d F Y');
          }
        }
  • Affichage dans templates/node--offre-emploi.html.twig :
        <div class="date">
          Poste à pourvoir le : {{ date_formatee }}
        </div>

3. Workflow de Développement Rigoureux​

Nous suivons un workflow précis pour garantir un historique de code propre et des déploiements fiables.

  • Stratégie de branche GitFlow :

    • Les fonctionnalités sont développées sur des branches feature/* depuis dev.

    • Les branches feature sont mergées dans dev une fois terminées.

    • La branche master reflète la production et n'est mise à jour que depuis des branches release/* ou hotfix/*.

  • Messages de commit Conventional Commits : Chaque commit doit respecter le format type(scope): description.

    • Exemple : feat(actualite): ajoute le champ pour épingler un article

    • Exemple : fix(formulaire): corrige la validation de l'email

4. La Configuration est du Code (Configuration Management)​

La structure du site (types de contenu, vues, champs, etc.) est gérée via des fichiers de configuration YAML et versionnée dans Git.

  • Aucune modification de configuration structurelle ne doit être faite directement sur les environnements de préproduction ou de production.

  • Toute modification de ce type doit être faite localement, exportée (drush config:export) et commitée.

  • Le déploiement se charge d'importer la configuration (drush config:import).

5. La Sécurité d'Abord (Security First)​

La sécurité n'est pas une option, c'est une exigence.

  • Ne jamais faire confiance aux données utilisateur : Toujours assainir les données affichées (Drupal le fait bien si l'on utilise ses APIs).

  • Aucun secret dans le code : Les clés d'API, mots de passe de base de données ou autres informations sensibles ne doivent JAMAIS être commités dans le dépôt Git. Utilisez le fichier settings.local.php (ignoré par Git) et les variables d'environnement fournies par la plateforme d'hébergement.

6. La Performance par Conception​

La performance doit être une considération à chaque étape du développement.

  • Optimiser les requêtes : Éviter de charger des objets ou des entités dans des boucles.

  • Utiliser les métadonnées de cache de Drupal : S'assurer que tous les rendus dynamiques sont associés aux cache tags et cache contexts appropriés pour permettre une invalidation de cache fine et efficace.

  • Optimiser les images : Utiliser les styles d'image de Drupal pour servir des images redimensionnées et compressées.

7. L'Accessibilité n'est pas une Option​

Nous visons une conformité élevée au RGAA.

  • Utiliser systématiquement du HTML sémantique (<nav>, <main>, <footer>, etc.).

  • Fournir des alternatives textuelles (alt) pertinentes pour toutes les images informatives.

  • Assurer que toutes les fonctionnalités sont utilisables au clavier.

  • Utiliser les rôles et attributs WAI-ARIA lorsque le HTML sémantique ne suffit pas.

8. Environnements Cohérents et Reproductibles​

Pour éviter les problèmes du type "ça marche sur ma machine", tout développement doit être fait via l'environnement local fourni par Docker.

  • Lancez l'environnement avec docker-compose up -d

  • Utilisez docker-compose exec [service] [commande] pour exécuter des commandes (comme Drush) à l'intérieur des conteneurs.