Collaboration et bonnes pratiques en matière de développement
En travaillant avec un grand nombre d’équipes de développement dans de nombreux projets et organisations, nous avons constaté qu’il est utile de réunir certaines de nos connaissances. Certaines d’entre elles sont liées à AEM, mais la majorité concernent le développement frontal à usage général ou sont simplement des directives communes portant sur la collaboration dans une équipe de développement.
Vous pouvez lire certains de ces éléments et penser qu’ils sont généralement compris comme relevant du bon sens par les développeurs. Nous sommes d’accord, et c’est un excellent signe que vous êtes prêt à travailler en collaboration sur des projets AEM avec d’autres développeurs.
À ce stade, il s'agit simplement d'un ensemble de leçons tirées de nos engagements dans un ensemble croissant de projets.
GitHub
Créer des demandes d’extraction
Si vous travaillez sur un projet avec plusieurs développeurs, il est rarement préférable de pousser directement vers main. Lorsque votre projet est en production, les modifications de code qui sont fusionnées ou transmises à main signifient souvent qu’elles sont mises en production. La protection de votre branche main est un bon mécanisme pour s’assurer que les gens ne poussent pas vers main par accident, ce qui est particulièrement conseillé avec un site en production. Limitez la portée de votre requête d’extraction à ce qui se trouve dans le titre/la description de la requête de tirage.
Étiquette des demandes d’extraction
Si vous ouvrez une demande d’extraction, veillez à inclure une URL vers une page (ou un certain nombre de liens vers des pages) de votre branche, où le réviseur ou la réviseuse peut voir votre code en action. Si vous mettez à jour le code d’un bloc existant, veillez à inclure le lien qui contient le bloc que vous mettez à jour, car le réviseur ou la réviseuse ne sait peut-être pas où ce bloc est utilisé pour tester sa fonctionnalité.
Robot Github AEM
Le robot Github d’AEM et la configuration standard du projet Boilerplate vérifient la liaison de vos informations CSS/JS et PageSpeed en termes de performances web, d’accessibilité, d’optimisation pour les moteurs de recherche et de bonnes pratiques. Ne soumettez pas de demande d’extraction pour révision qui comporte des erreurs de lint ou qui n’a pas un score Lighthouse de 100 dans les informations sur la vitesse de page.
Révisions
Il est recommandé de faire réviser votre code par le responsable ou le développeur principal du projet sur lequel vous travaillez. Pour que le réviseur ou la réviseuse puisse afficher un score de performances PageSpeedInsight réaliste, incluez des liens vers l’environnement de .live mis en cache.
Si vous êtes un responsable de la maintenance ou un développeur principal sur un projet qui n’est pas en production et que vous ajoutez du code ou modifiez votre propre code, il est parfois inutile de faire réviser vos RP par des pairs et il est souvent correct de fusionner vos propres RP sans révision par des pairs.
Fusion des demandes d’extraction
Fusionnez uniquement vos propres requêtes d’extraction. Si la personne qui a ouvert la demande d’extraction peut fusionner sa propre demande d’extraction, l’auteur du code est la personne idéale à fusionner. Dans certains cas, l’auteur indique spécifiquement que cette opération peut et doit être fusionnée par une autre personne. Dans ce cas, un responsable (développeur principal) du projet doit se sentir libre de fusionner une demande d’extraction.
Même si une demande d’extraction est approuvée, vous devez toujours vérifier auprès de l’auteur de la demande d’extraction si elle est prête à fusionner.
Pour les tâches toujours en cours, l’ouverture d’une demande d’extraction de brouillon permet également d’éviter la fusion accidentelle.
Branches partagées
Il est recommandé de considérer les branches pour les requêtes d’extraction individuelles comme un emplacement privé du développeur qui a créé la branche. Ne vous contentez pas de pousser dans les branches d’autres développeurs sans avoir été invité à le faire. Il existe des situations où les personnes collaborent sur des demandes d’extraction, mais il doit s’agir d’un accord explicite.
Développement basé sur les liaisons (à l’échelle)
AEM fonctionne parfaitement dans un développement à grande échelle basé sur les liaisons avec des devops et CI/CD intégrés. Cela signifie que vous fusionnez un grand nombre de petites demandes d’extraction dans la production principale, mais que les efforts d’Assurance/de révision de la qualité peuvent être adaptés à l’impact d’une petite modification. Personne ne souhaite passer en revue et tester les demandes d’extraction volumineuses, et les branches de longue durée comportant de nombreuses modifications ont tendance à être difficiles (et dangereuses) à fusionner.
Linting
Ne modifiez pas les configurations de lingage (eslint airbnb-base et stylelint) à moins d'avoir une très bonne raison. Les préférences personnelles ne sont pas une bonne raison. La modification des liens rend très difficile le déplacement des développeurs d’un projet à l’autre. Arguer si quelque chose est une bonne raison de modifier la configuration de la liaison est généralement beaucoup plus d'effort que de simplement dire catégoriquement non.
CSS
Isoler les blocs du sélecteur CSS
Les blocs AEM fonctionnent le plus souvent en tant que composants de manière collaborative dans le même DOM/CSSOM. Cela signifie que vous devez écrire vos sélecteurs CSS dans un .css de bloc de manière à isoler votre CSS de l’impact sur la disposition des éléments à l’extérieur de votre bloc. Pour ce faire, la méthode la plus simple consiste à s’assurer que chaque sélecteur CSS du .css d’un bloc s’applique uniquement à ce bloc.
Cascade dans CSS
Utilisez judicieusement vos noms de classe CSS. Certaines classes et variables CSS sont utilisées sur différents blocs et d’autres ne sont pas censées être utilisées en dehors de votre bloc. Il est recommandé de faire précéder de nom de bloc les classes et les variables privées de votre bloc. À l’inverse, si des classes CSS et un contexte CSS doivent être hérités (souvent, ils peuvent être créés), ces classes et variables ne doivent pas être précédées de préfixe.
Mise en retrait CSS et ordre des propriétés
En dehors d’une requête de tirage sur une refactorisation CSS, ne modifiez pas le séquencement sur les propriétés ou la mise en retrait dans les fichiers CSS que vous touchez dans une requête de tirage fonctionnelle. Chaque développeur possède des préférences différentes dans l’ordre de tri des propriétés ou de la mise en retrait. Assurez-vous que la différence que vous voyez dans votre requête de tirage est isolée des modifications que vous souhaitez réellement examiner avant de l’envoyer.
Complexité des sélecteurs CSS
Ne laissez pas vos sélecteurs CSS devenir complexes et illisibles. Souvent, il est préférable de décorer des classes/éléments CSS supplémentaires sur votre DOM et d’écrire un CSS lisible à la place. Les sélecteurs CSS complexes sont également souvent plus difficiles à gérer et plus fragiles que les équivalents dans JS.
Dénomination CSS
Nommer vos classes de manière simple et intuitive est utile pour les autres développeurs. Évitez l’espace de noms, sauf si nécessaire dans la portée d’un projet. Il n'est souvent pas nécessaire de préciser le type ou l'origine (p. ex. le nom de votre système de conception) d’une variable CSS qui doit être utilisée dans l’ensemble du projet.
Utilisation des attributs ARIA pour le style
Dans de nombreuses situations, vous ajoutez des attributs ARIA pour l’accessibilité. Comme ceux-ci ont des sémantiques bien définies comme expanded ou hidden qui sont comprises par tous les développeurs, dans la plupart des cas, il n'est pas vraiment nécessaire de trouver des classes supplémentaires dans votre vocabulaire qui ont des sémantiques inconnues.
Mobile en premier
En général, les projets Web devraient être développés « Mobile First ». Cela signifie que votre CSS sans requête de média doit effectuer le rendu d’un site mobile. Ajoutez des requêtes de média pour étendre la disposition de la tablette et du bureau.
Points d'arrêt
Utilisez généralement 600px, 900px et 1200px comme points d’arrêt, tous min-width. Ne mélangez pas min-width et max-width. N’utilisez différents points d’arrêt que dans des cas exceptionnels, lorsque vous comprenez bien pourquoi cela est nécessaire.
Less, Sass, PostCSS, Tailwind et amis.
Si vous travaillez dans le contexte d’une organisation plus grande, veillez à ne pas ajouter de dépendance à un préprocesseur ou à un framework CSS de votre choix personnel sans l’accord de l’ensemble de l’équipe et de l’organisation. Comme il existe de nombreuses préférences personnelles dans ce domaine, il est difficile de gérer le code si chaque projet ou chaque bloc au sein d’un projet utilise des technologies différentes.
La solution la plus simple est de s’appuyer sur la réinitialisation croissante des fonctionnalités CSS, qui est prise en charge par les navigateurs.
Fonctionnalités CSS modernes
Assurez-vous que les fonctionnalités que vous utilisez sont correctement prises en charge par les navigateurs sans cesse renouvelés. Selon les caractéristiques, un support plus ou moins omniprésent peut être acceptable.
JavaScript
Frameworks
Sur la plupart des sites web, les frameworks sont surchargés pour des problèmes de mise en page simples, en dehors des fonctionnalités de type application. Les frameworks présentent souvent des problèmes de performances web (Lighthouse et Core Web Vitals), en particulier s’ils sont sur le chemin de la LCP ou introduisent des TBT, tout en essayant de résoudre des problèmes triviaux. Restez simple.
Si vous utilisez des frameworks Javascript, veillez à ne pas introduire de dépendance dans un Framework JS ou une bibliothèque de votre choix sans l’approbation de l’ensemble de l’équipe et de l’organisation. Comme il existe de nombreuses préférences personnelles, il est difficile de gérer le code si chaque projet ou chaque bloc au sein d’un projet utilise différentes technologies.
La solution la plus simple consiste à s’appuyer sur les fonctionnalités croissantes prises en charge par les navigateurs.
Construire la chaîne d'outils
Les chaînes d’outils de création différentes d’un projet à l’autre compliquent l’intégration des nouveaux développeurs et ajoutent souvent à la complexité. Assurez-vous de ne pas introduire de dépendance liée à vos préférences personnelles sans l’approbation de l’ensemble de l’équipe et de l’organisation.
La solution la plus simple est de garder l’ensemble du projet sans version.
Fonctionnalités JavaScript modernes
Assurez-vous que les fonctionnalités que vous utilisez sont correctement prises en charge par les navigateurs sans cesse renouvelés. Selon les caractéristiques, un support plus ou moins omniprésent peut être acceptable. Bien qu’AEM puisse être utilisé avec n’importe quel navigateur, lib-franklin.js dépend des navigateurs qui prennent en charge le import() dynamique. Toute fonctionnalité prise en charge par l’ensemble des navigateurs qui prennent en charge le import() dynamique doit être considérée comme sûre. Techniquement, bien sûr, les navigateurs plus anciens (par ex. IE) peut être pris en charge par les projets AEM, mais ceux-ci nécessitent une personnalisation importante.
Toutes les fonctionnalités n’ont pas les mêmes conséquences si un navigateur ne les prend pas en charge, certaines peuvent être cosmétiques et d’autres peuvent empêcher le site de fonctionner. Un exemple courant est le « chaînage facultatif ». Si un navigateur ne prend pas en charge le « chaînage facultatif », une utilisation unique peut avoir des conséquences fatales pour la page entière.
Chargement des bibliothèques tierces
N’ajoutez pas de bibliothèques tierces à votre <head> via head.html, car elles se trouveront dans le chemin critique du chargement de contenu et seront souvent chargées lorsqu’elles ne sont pas nécessaires. Ajoutez les dépendances, le cas échéant, via loadScript(), au bloc spécifique ayant l’exigence correspondante.
Dans le cas de bibliothèques tierces plus volumineuses, vous pouvez même envisager d’utiliser un IntersectionObserver pour vous assurer de ne les charger que lorsque le bloc qui en dépend est en fait défilé dans la vue.
Bibliothèque AEM (aem.js)
La bibliothèque AEM (généralement hébergée en aem.js dans un projet) n’est actuellement pas minimisée et obscurcie pour faciliter le débogage. Nous déconseillons d’y apporter des modifications en fonction du projet et recommandons plutôt de conserver les extensions spécifiques au projet en dehors de la bibliothèque. Nous acceptons les demandes d’extraction via github, si vous souhaitez proposer des modifications/correctifs qui sont universellement applicables.
<head>
Les <head> diffusées à partir du serveur dans le cadre du balisage HTML doivent rester minimales et exemptes de technologies marketing telles qu’Adobe Web SDK, Google Tag Manager ou d’autres scripts tiers en raison de l’impact sur les performances. Il est également déconseillé d’ajouter des scripts ou des styles intégrés aux <head> pour des raisons de performances et de gestion du code.
Minimisation
En règle générale, il s’agit d’une complexité supplémentaire sans grand avantage, sauf si vous disposez de fichiers JS/CSS vraiment volumineux qui, encore une fois, seraient antimotifs. Avec Edge Delivery, la façon dont le code est structuré autour des blocs, les fichiers doivent généralement être de petite taille et la miniaturisation ne doit pas faire une grande différence. Bien sûr, vous pouvez comparer LHS pré/post minimisation.
La minimisation rend le code légèrement plus difficile à déboguer et vous avez besoin de mappages sources. La miniaturisation nécessite également une étape de création supplémentaire qui peut potentiellement ralentir le travail de développement du site. Vous n’avez donc envie d’y aller que si cette complexité supplémentaire présente un avantage tangible
Contenu dans Sharepoint / Google Drive
Commencer le développement avec du contenu
Avant d’écrire une ligne de code, créez votre (exemple) contenu dans un document Word ou Google (ou une feuille de calcul). Assurez-vous qu’il est adapté à la création et partagez-le avec des membres de votre équipe qui ont de l’expérience dans le soutien aux auteurs. Il faut une expérience d’assistance pour comprendre quelles structures de contenu sont faciles à comprendre et à recréer pour les auteurs et les autrices. Une fois que vous avez défini une structure de contenu contenant tous les éléments dont vous avez besoin pour votre bloc et que vous l’avez révisé, vous pouvez commencer à développer votre code CSS et JS.
Utilisation /drafts
Le cycle de vie du contenu est très différent du cycle de vie du code. Si vous proposez des modifications à une structure de contenu existante dans votre code ou proposez un nouveau bloc, ne faites pas simplement ces modifications sur la page sur laquelle vous travaillez. Copiez la page dans votre dossier /drafts/<yourname>/ et apportez-y des modifications.
Une fois vos modifications de code fusionnées dans main , vous pouvez demander aux auteurs de copier ou de fusionner votre contenu avec le contenu situé en dehors de votre dossier /drafts/.
Rétrocompatibilité des nouvelles fonctionnalités
En particulier dans les environnements de production, il est important que les modifications anticipées de la structure de contenu soient rétrocompatibles avec le contenu existant. Idéalement, le code en cours de fusion ne doit pas avoir d’impact sur le site web ni nécessiter une refactorisation du contenu. La nouvelle fonctionnalité n’est disponible que lorsque du nouveau contenu est mis en place par le biais d’un cycle de prévisualisation et de publication. Bien sûr, cela ne s’applique pas à des éléments tels que les modifications de conception du contenu existant ou les correctifs fonctionnels.
Utiliser du contenu pour les ressources « statiques »
En règle générale, il n’est pas recommandé de valider les fichiers binaires dans votre référentiel GitHub. Même les ressources statiques textuelles, par exemple les fichiers HTML ou les SVG, ne doivent être placées dans GitHub que dans des cas exceptionnels. Une bonne raison d’ajouter un SVG à votre référentiel Git est s’il est référencé à partir de code. Ne validez rien qui soit lié au processus de création de contenu ou qui puisse faire partie d’un processus de création. Il existe certaines exceptions (généralement liées aux clients hérités et non-navigateurs) qui nécessitent un certain ensemble de ressources fixes qui ne peuvent pas être générées et manipulées dynamiquement par AEM, mais en général si vous constatez un grand ensemble de ressources statiques (par exemple, . images, etc.) ou un fichier HTML dans une requête de tirage, il s’agit probablement d’une mauvaise pratique.
Utiliser du contenu pour les chaînes/littéraux
Les chaînes qui sont affichées pour les utilisateurs finaux et qui pourraient éventuellement être traduites ou modifiées à un moment donné doivent toujours être modifiables et sourcées à partir du contenu (par exemple, placeholders, ou d'autres feuilles de calcul ou documents). Si vous disposez d’une chaîne littérale qui s’affiche en tant que texte pour le visiteur de votre site web dans votre code javascript ou css, il est recommandé de la remplacer par une référence au contenu (par exemple, placeholders).