Contribuer au DSFR

Avant de commencer à utiliser le Système de Design de l'État (ci-après, DSFR) , veillez à prendre connaissance des conditions générales d'utilisations. Si vous souhaitez contribuer au DSFR, veuillez prendre connaissance des documents relatifs à la cession des droits d'auteur et du certificat garantissant l'originalité de votre contribution.

Installation

Installation locale

Le DSFR est basé sur une architecture NodeJS, il est donc nécessaire d’installer une version récente de nodeJs. Dans le terminal nous utiliserons les commandes de npm ou yarn pour lancer les scripts.

Le dépôt est disponible à cette adresse : GitHub - GouvernementFR/dsfr: Système de Design de l'État

Afin de pouvoir commencer à développer et contribuer au DSFR, assurez-vous tout d'abord de faire un fork du projet depuis votre compte github (Fork a repo - GitHub Docs )

Il suffit ensuite de cloner votre fork, en téléchargeant les sources depuis le bouton “clone” de github, ou via un terminal avec commande : git clone https://github.com/VOTRE_NOM_UTILISATEUR_GITHUB/dsfr

La branche **dev-X.X.X** (X.X.X correspondant au numéro de version à venir) est la principale branche de travail - la branche main correspondant aux versions de productions livrées aux utilisateurs. Il est donc nécessaire de créer de nouvelles branches de travail pour l'ajout et la modification de packages depuis la branche dev. (Voir la section Utilisation > Git, pour le fonctionnement détaillé).

Une fois le projet récupéré, il est nécessaire d'installer les dépendances (node_modules) avec :

yarn 

OU

npm i 

OU

Enfin, il est nécessaire de lancer un serveur local pour visualiser les pages d’exemples :

yarn serve

OU

npm run serve

Un serveur local sera alors lancé sur l'adresse localhost:8080. Accéder à http://localhost:8080/example/ pour voir la liste des exemples.

Packages

Le DSFR est un monorepo proposant différents composants, listés dans le dossier src/component.

Un composant doit avoir une arborescence de type :

Le dossier example comprend les fichiers ejs d’exemple (ils utilisent les templates du composant en passant des valeurs d’exemple en paramètre). Le dossier styles contient les fichiers .scss permettant la génération du css du composant. Le dossier templates contient les templates des composants (la mise en forme html).

Certains de ces packages sont dépendants les uns des autres. Chacun de ces packages possède donc un fichier package.yml, listant l'ensemble de ses dépendances à d'autres composants du DSFR.

Celui-ci gère les imports et le wrapper des examples html générés ainsi que l'implémentation des http://readme.md . Il est structuré de cette façon :

id: buttons (nom du package)
title: Boutons (nom du composant, en français)
description: description insérée dans le readme
doc: lien vers la documentation
wrapper: col-8 (le conteneur dans lequel on insert l'example)
styles: (liste des packages dont le css dépend)
  - core
scripts: (liste des packages dont le js dépend)
  - core
follow:   (pas de dépendance à link mais doit etre placé après link)
  styles:
    - links
example: (dépendances sur la page d'exemple uniquement)
  styles:
    - header

Utilisation

Sass

Le DSFR utilise Sass pour la génération automatique des styles liés à chaque composant. Chacun d'entre eux possède une structure identique à ce niveau, par exemple le composant button :

/src/component/button
└── styles
    ├── _module.scss
    ├── _scheme.scss
    ├── _legacy.scss
    ├── _tool.scss
    ├── _setting.scss
    └── module/
        └── _buttons-group.scss
└── index.scss
└── main.scss
└── legacy.scss

Il peut donc y avoir plusieurs fichier .scss, mais seuls main.scss à la racine du composant, et _module.scss sont obligatoires, et chacun à son propre rôle :

  • main.scss : Fichier principal du composant servant d'entrée, et composé uniquement d'@import. Il importe le fichier index ainsi que des fichiers modules du composant (obligatoire)
  • index.scss : Fichier secondaire du composant, aussi composé d'@imports, importe uniquement les fichiers de settings et tools du composant ainsi que l'index.scss des composants dépendants. (obligatoire)
  • _module.scss : Comprend l'ensemble des styles du module (obligatoire)
  • _scheme.scss : doit contenir tous les styles liés aux couleurs, afin de gérer la thématisation. (optionnel)
  • legacy.scss : Permet de générer un fichier séparé pour le support navigateur (facultatif)
  • _legacy.scss : Contient tous les styles uniquement lié au support des anciens navigateurs (facultatif)
  • _setting.scss : Contient les variables sass utilisées par le composant (optionnel)
  • _tool.scss : Contient les functions et mixins pouvant être utilisés par le composant, par exemple la gestion des token d'espacements (optionnel)
  • modules/_buttons-group.scss : Example de sous-composant permettant d'alléger _module.scss, qui importe ce fichier

Javascript

Certains packages font utilisation de javascript, afin d'apporter une couche interactive à ceux-ci. C'est le cas par exemple du package navigation, où le javascript est utilisé pour déplier les sous-menus. La couche javascript est structurée comme ceci, par exemple pour le composant navigation :

/src/component/navigation
└── script
    └── navigation/
        ├── navigation-item.js
        ├── navigation.js
        ...
└── api.js
└── index.js
└── main.js
api.js : importe depuis core l'objet global qui contient les classes, variables et instances du DSFR (Fichier identique dans chaque package avec du js).
index.js : Ajoute à l'objet global api des définitions de classes et variables spécifiques au composant. 
main.js : importe l'index et permet l'initialisation du composant.

Un Dossier script qui contient un dossier par fonctionalité js, ici navigation puis :

  • navigation.js (ou nom-classe.js) contient le code de la fonctionnalité js, structurée en classes instanciables (es6) .

Lors du yarn release, le javascript est compilé en version "module" (es6) et "nomodule" (es5), ainsi qu'en version .min et .map.En mode développement, yarn build permet de regénérer uniquement la version .module.js (es6 non minifié)

EJS

Nous utilisons au sein du DSFR, le langage de template EJS (documentation officielle), permettant la génération des pages d'exemples au format HTML, ainsi que les snippets de code de manière automatisée.

Les fichiers ejs sont séparés dans 2 dossiers, par exemple pour le package callout :

/src/component/callouts
└── example
    ├── index.ejs
    └── samples/
        └── callout-default.ejs
└── template
    └── ejs
        └── callout.ejs

Dans le dossier exampleìndex.ejs est la page d'exemple publiée, elle affiche les différents exemples grâce à la fonction sample() (qui inclut l'exemple et le snippet de code) Le dossier sample contient les différents exemples (inclusion des templates avec des données d'exemples)

Dans le dossier templates, on insère ici les templates dans un sous-dossier nommé en fonction du système de templating utilisé (ejs pour l'instant). Ces templates sont paramétrables pour y injecter des données. Chaque fichier possède une documentation sommaire détaillant ces paramètres.

Pour accéder aux fonctions du core (comme includeClasses() et includeAttr()), chaque template inclut l'index.ejs de core au début du fichier : <% eval(include('../../../core/index.ejs')); %>

Afin de générer tous les exemples HTML utilisez yarn release. Ou, plus spécifiquement avec yarn build, le paramètre -h de yarn build permet de reconstruire uniquement l'html : yarn build -h [-p nomPackage], avec -p pour préciser le(s) package(s).

Git

Branches

Afin de travailler sur un nouveau package, ou un correctif d'un package existant, il est nécessaire de créer une nouvelle branche à partir de la branche dev. git checkout -b prefixe/ma-branche dev

Nommage des branches

Afin d'organiser et d'identifier rapidement la nature du contenu des branches, il est nécessaire de préfixer les branches : feat/nom-de-la-branche pour les nouvelles fonctionnalités ou nouveaux composants. fix/nom-de-la-branche pour les correctifs apportés sur des fonctionnalités ou composants existants.

Commits

Nous utilisons des conventional commits qui doivent donc s'écrire sous la forme suivante :

<type>[optional scope]: <description en français>

[optional body]

[optional footer(s)]

Les valeurs possibles pour le type de commit sont :

  • fix : un commit de type fix permet de corriger un bug ([PATCH]).
  • feat : un commit de type feat permet d'introduire une nouvelle fonctionnalité ([MINOR]).
  • D'autres types que feat et fix peuvent être utilisés, nous utilisons @commitlint/config-conventional, qui recommande l'utilisation des principaux types suivants : build, chore, ci, docs, style, refactor, perf, test.
  • BREAKING CHANGE : un commit avec un footer BREAKING CHANGE introduit un changement important dans le code ([MAJOR]).

Les messages de commits sont écrits en français (exception faite des mots réservés par conventional commit, ainsi que les termes techniques).

Exemple de commit simple :

feat: ajout du composant Alerte 

Exemple de commit avec scope le nom du composant ou de la f, description et BREAKING CHANGE footer

fix(core): maj mixin: ancien-nom devient nouveau-nom

BREAKING CHANGE: nouveau nom pour la mixin ....

Signature des commits

Afin de garantir l'originalité des contributions, nous demandons aux contributeurs de signer leurs commits et/ou de nous faire parvenir le certificat de garantie de l'origine du développeur signé.

Pour signer un commit :

git commit --signoff (ou git commit -s)

Proposer une pull request

Important

Avant de proposer une pull request , assurez vous que vous respectez la garantie d’origine de vos développements, et pour les personnes n'étant pas des agents de l’État, que vous avez pris connaissance des documents relatifs à la cession des droits d’auteur, document à nous transmettre signé.Toute ‘pull request’ ne respectant pas ces pré-requis sera systématiquement rejetée.

Pour contribuer sur le git DSFR, il convient d’utiliser une “pull request” (PR). Lorsque vous estimez que votre développement est terminé et qu'il peut-être révisé par l'équipe DSFR, vos devez créer une pull request depuis github (Pull requests · GouvernementFR/dsfr ) ou github cli (gh). La pull request suit les même règles de nommage décrites précédemment (branches, commits), à savoir le conventional commits. Une description détaillant le problème à résoudre, la façon dont la contribution résout le problème et toute autre information utile à la revue de code est fortement conseillée!

La pull request doit être faite depuis la branche de votre fork vers la branche dev-X.X.X du dépôt officiel

Compilation

La compilation des sources permet de créer un dossier dist, exemple et .config à la racine du projet. Le dossier dist contient les fichiers CSS et JS compilés, ainsi que les favicons et l'ensemble des fontes utilisées au sein du DSFR.

Le dossier .config contient les variables générales JS et SCSS ainsi que la configuration nécessaire au build. Plus particulièrement le fichier config.json répertorie toute l’arborescence de src, les dépendances et leur ordre qu’il récupère depuis les fichiers package.yml de chaque package et folder.yml pour les dossier (src, component, page, pattern)

Le dossier example contient les exemples HTML générés depuis les samples ejs. L'ordre des imports css et js est défini par l'ordre des dépendances dans le package.yml

La commande générale pour lancer la génération des fichiers dist, des exemples, ainsi que les tests est :

yarn release

En mode développement, il est possible d'utiliser la commande :

yarn build

Cette commande permet de générer uniquement les fichiers css/js/html. Cette commande est plus rapide puisqu'elle n’exécute pas les test, et ne compile pas les fichier .map, .md, .min.css, .nomodule.js...
De plus, grâce au paramètre -p il est possible de spécifier uniquement les packages que l'on souhaite recompiler.

Pour voir les différents paramètres disponibles : yarn build --help

Autres commandes

Icônes

La gestion des icônes se fait à l'aide d'une webfont, chargée directement via CSS en base64. Celle-ci est générée automatiquement à partir des fichiers .svg se trouvant dans le dossier src/core/icon/svg/. Il est donc possible d'ajouter des icônes, en ajoutant des fichiers .svg à ce dossier, et en relançant le build

yarn build --clean

Sassdoc

Des commentaires spéciaux sont utilisés sur l'ensemble des fichier scss, afin de permettre la génération d'une Sassdoc automatiquement, documentant l'ensemble des mixins et functions utilisés sur le DSFR :

yarn styleguide

Cette commande permet la génération de la doc dans le dossier sassdoc, à la racine du projet.

Tests

Afin de s'assurer de la qualité du code, nous utilisons des tests automatisés qu'il est nécessaire d'exécuter régulièrement pour vérifier que le code du DSFR reste valide et cohérent, notamment avant d'effectuer des pull requests sur le dépôt de production, et avant publication sur NPM.

Ces tests sont exécutés lors de la commande : yarn release, ou plus spécifiquement avec :

Qui peut être combiner avec -p nomPackage pour spécifier un ou des package(s).

Pour voir les différents paramètres disponibles : yarn build --help

Tests Sass

Afin de tester les différentes functions et mixins, nous utilisons jest et sass-true, afin d'effectuer une batterie de tests, présents dans un fichier tests/_sass-tests.scss au sein de certains packages.

Ces tests permettent de vérifier que le code renvoyé par ces derniers est bien conforme. (Par exemple, vérifier que la mixin de line-height renvoie bien la bonne valeur). Ces tests sont effectués lors du yarn release, ou plus spécifiquement avec :

yarn build --test

Tests d'accessibilité

Pour tester de manière automatisée l'accessibilité des composants du DSFR, nous utilisons Pa11y sur les pages de tests des différents packages. Ces tests sont effectués lors du "yarn release", ou plus spécifiquement avec :

yarn build --test

Afin d'exclure un élément à tester au niveau des pages de test, il est possible de lui attribuer une classe spécifique .is-pa11y-hidden Les tests se jouent automatiquement sur chaque page de test de package, en mode normal puis en Darkmode

Lint

Pour vérifier de manière automatisée les erreurs de syntaxe, de mise en forme du code, ou de non respect des bonne pratiques, nous utilisons esLint lors du yarn release ou plus spécifiquement avec :

yarn build --test

La configuration est présente dans le fichier .eslintrc.json. Elle reprend en grande partie la configuration standard de esLint.