Bibliothèque pour la cartographie de l’offre de médiation numérique

À propos

Il s'agit d'une collection d'éléments Angular à destination des projets qui ont pour vocation d'intégrer des fonctionnalités liées au recensement de l'offre de médiation numérique sur le territoire Français et à l'orientation des usagers vers les services de médiation numérique les plus adaptés à leurs besoins.

Table des matières

• 🪧 À propos
• 📦 Prérequis
• 🚀 Installation
• 🛠️ Utilisation
• 🤝 Contribution
• 🏗️ Construit avec
• 📚 Documentation
• 🏷️ Gestion des versions
• 📝 Licence

Prérequis

• Git : Système de contrôle de versions distribué d'un ensemble de fichiers
• Node : Environnement d'exécution pour Javascript
• Yarn : Gestionnaire de paquets pour les produits développés dans des environnements Node

Node et Yarn peuvent être installés via nvm qui permet d'obtenir et d'utiliser rapidement différentes versions de Node via la ligne de commande.

Installation

Pour l'utiliser dans un projet Angular

• Avec yarn : yarn add @gouvfr-anct/mediation-numerique
• Avec npm : npm install @gouvfr-anct/mediation-numerique

Pour contribuer au développement

Ce projet a été construit dans un espace de travail Angular, pour fonctionner correctement, il est nécessaire de le cloner dans un environnement similaire :

En utilisant l'espace de travail original

• Suivre la procédure d'installation du projet Client Base
• Une fois que l'espace de travail est prêt, il faut créer le dossier @gouvfr-anct dans projects
• Puis cloner le dépôt en local dans le dossier projects/@gouvfr-anct : git clone [email protected]:anct-cartographie-nationale/mediation-numerique.git

En utilisant un projet Angular déjà existant

• Dans le dossier du projet Angular cible, lancer la commande de génération de bibliothèques : ng generate library @gouvfr-anct/mediation-numerique
• Cette commande va adapter les fichiers package.json, angular.json et tsconfig.json pour adapter le projet au développement de la bibliothèque qui vient d'être générée dans le nouveau dossier projects
• Créer le fichier tsconfig.base.json à la racine du projet et y copier le contenu de tsconfig.json en supprimant la propriété compilerOptions.paths, pour éviter une duplication il est possible de faire en sorte que tsconfig.json étende tsconfig.base.json en ajoutant seulement la propriété compilerOptions.paths
• Optionnellement, il est possible d'adapter le code généré dans angular.json et tsconfig.json, ainsi que l'arborescence dans le dossier projects afin d'ajouter le @ manquant pour correspondre au chemin projects/@gouvfr-anct/mediation-numerique
• Supprimer le dossier mediation-numerique contenant le code de la bibliothèque générée
• Puis cloner le dépôt en local à la place : git clone [email protected]:anct-cartographie-nationale/mediation-numerique.git
• Attention à bien installer les paquets npm dont la bibliothèque a besoin dans le projet Angular de base :
  • @angular/flex-layout
  • leaflet
  • geojson
  • @asymmetrik/ngx-leaflet

Dans tous les cas

Installer Husky

Husky est un outil de gestion des hooks git pour effectuer des tâches automatiques

Mise en place de Husky dans le dossier du projet @gouvfr-anct/mediation-numerique :

npx husky install

Rendre exécutable les fichiers qui contiennent les hooks :

chmod a+x .husky/commit-msg
chmod a+x .husky/pre-commit

Utilisation

Ces commandes servent dans un contexte de développement de la bibliothèque et doivent être exécutées depuis la racine de l'espace de travail, c'est-à-dire depuis le dossier parent du dossier projects.

Construction

Exécuter yarn build @gouvfr-anct/mediation-numerique pour construire le projet. Les fichiers de sortie sont écrits dans le dossier dist/@gouvfr-anct/mediation-numerique/.

Test

Exécuter yarn test @gouvfr-anct/mediation-numerique pour tester le projet.

Si suite à un build le dossier dist contient @gouvfr-anct/mediation-numerique, certains tests sont en erreur, pour résoudre cela, il faut soit supprimer le dossier @gouvfr-anct/mediation-numerique dans dist, soit exécuter la commande npx ng test @gouvfr-anct/mediation-numerique directement dans le dossier projects/@gouvfr-anct/mediation-numerique.

ESLint

Exécuter yarn lint @gouvfr-anct/mediation-numerique pour une analyse statique des fichiers .ts du projet.

Commit lint

Exécuter yarn commitlint --from HEAD~1 pour valider la syntaxe du dernier commit.

Prettier

Exécuter yarn prettier pour mettre à niveau la syntaxe de l'ensemble des fichiers du projet.

Contribution

Nommage des branches

• Avant de créer une nouvelle branche de travail, récupérer les dernières modifications disponibles sur la branche main
• La nouvelle branche de travail doit ête préfixée par build/, chore/, ci/, docs/, feat/, fix/, perf/, refactor/, revert/, style/ ou test/ en fonction du type de modification prévu, pour plus de détails à ce sujet, consulter Conventional Commits cheat sheet
• Une branche portant une version à publier doit être de la forme release/X.Y avec X.Y égal au numéro de majeur et de mineur de la release, cela signifie donc que tous les patches sont à appliquer sur la même branche pour chaque version mineure. Cette organisation permet de gérer plusieurs versions de la bibliothèque en parallèle sans mettre en péril la rétrocompatibilité.

Commits

Convention

Les commits de ce repository doivent respecter la syntaxe décrite par la spécification des Commits Conventionnels

Signature

La branche main, ainsi que l'ensemble des branches de travail avec un préfixe valide requièrent que les commits soient signés :

• La documentation de GitHub indique comment configurer la signature des commits
• Les utilisateurs de keybase peuvent signer leurs commits avec leur clé GPG sur Keybase

Publier sur la branche principale

• La branche principale est main, il n'est pas possible de publier en faisant un push depuis un dépôt local
• Il faut forcément créer une nouvelle branche de travail avec l'un préfixe autorisé
• À chaque publication sur une branche de travail, le workflow Validate feature sur github actions vérifie
  • Qu'il est possible de créer un build sans erreur
  • Que la syntaxe correspond bien à ce qui est défini par Prettier
  • Que le code écrit en TypeScript respecte les conventions décrites par les règles ESLint
  • Que les messages des commits suivent le standard établi par Conventional Commits
• Une fois les développements terminés, il faut créer une pull request avec la banche de travail comme origin et la branche main comme destination.
• La pull request ne peut être fusionné que si :
  • Les étapes du workflow Validate feature sont valides
  • Les fichiers modifiés ont été revus par au moins une personne
  • Les commits ajoutés sont signés
• La branche de travail est supprimée automatiquement une fois qu'elle a été fusionnée

Déployer

Pour publier une nouvelle version, il faut que le numéro de version cible soit mis à jour dans le fichier package.json, que le fichier CHANGELOG.md soit mis à jour et que le commit de la version à publier porte un tag de la forme vX.Y.Z correspondant au numéro de version présent dans package.json.

Il est possible d'automatiser ce processus en utilisant la commande standard-version :

• Récupérer la version à publier depuis la branche main
• Vérifier la valeur du prochain tag avec la commande standard-version --dry-run
• Récupérer ou créer la branche release/X.Y correspondant à la majeure et la mineure indiquée par la commande précédente
• Lancer la commande standard-version qui
  • met à jour la version dans le fichier package.json
  • met à jour le fichier CHANGELOG.md
  • créé un nouveau commit
  • ajoute le tag correspondant à la version dans le fichier package.json
• Pousser la branche avec le tag git push origin release/X.Y --tags conduit à la publication d'une nouvelle version
• Si le numéro de version est le plus grand au sens de la priorité définie par la spécification de la gestion sémantique de version (11), alors il faut créer une pull request vers la branche main, il ne faut pas le faire si ce n'est pas le cas.

Construit avec

langages & Frameworks

• TypeScript est un langage open source construit à partir de JavaScript
• Angular est une boîte à outils open source pour construire des clients web

Outils

CLI

• Jest est une boîte à outils pour écrire des tests automatisés en JavaScript
• Eslint est un analyseur statique de JavaScript avec les plugins suivants :
• Prettier est un magnificateur de code source en JavaScript

CI

• Github Actions est l'outil d'intégration et de déploiement continu intégré à GitHub
  • L'historique des déploiements est disponible sous l'onglet Actions
• Secrets du dépôt :
  • NODE_AUTH_TOKEN : Clé d'accès NPM pour publier sur l'organisation @gouvfr-anct

Déploiement

• npm est le registre de référence pour les paquets Node.
  • Organisation : @gouvfr-anct
  • Paquet : @gouvfr-anct/mediation-numerique

Documentation

Table des matières

• Mise en place
  • Configurations
  • Modules
• Éléments disponibles
  • Shared
  • Map
  • Structure

Mise en place

Configurations

Les modules Map et Structure ont besoin d'être configurés en utilisant la méthode forRoot qui prend en paramètre des implémentations côté projet afin de les injecter dans les éléments de la bibliothèque qui en ont besoin.

• Map
  • GeometryPolygonConfiguration : Configuration d'une forme de type FeatureCollection<Polygon> à afficher sur la carte
  • ZoomLevel : Configuration des niveaux de zooms min, regular, userPosition et max
  • InitialPosition : Configuration de la position initiale de la carte par la latitude et la longitude
  • MarkerType : Configuration des types de marqueurs structure, mdm, conseillerFrance, user
  • GeojsonService : Repository disposant des méthodes getMDMGeoJson et getTownshipCoord
• Structure
  • SearchService : Repository disposant des méthodes getCategoriesAccompaniment, getCategoriesOthers, getCategoriesTraining et getIndex
  • StructureService : Repository disposant des méthodes getStructure et sendMailOnStructureError

Les configurations peuvent être définies sous forme d'objets ou d'énumérations dans un dossier config du projet, les repositories peuvent être définis comme des services Angular classiques sans providedIn: 'root', car c'est le module de la bibliothèque qui se charge de l'injection dans les providers.

Modules

• Shared
  • ButtonModule
  • SvgIconModule
  • TextInputModalModule
  • ModalModule
  • TooltipModule
  • DayModule
  • PhoneModule
• Map
  • MapModule
• Structure
  • StructureModule

Éléments disponibles

Shared

Composants

• ButtonComponent
  • Sélecteur : app-button
• SvgIconComponent
  • Sélecteur : app-svg-icon
• TextInputModalComponent
  • Sélecteur : app-text-input-modal

Directives

• ModalOutsideDirective
  • Sélecteur : [clickOutside]
• TooltipDirective
  • Sélecteur : [app-tooltipDirective]

Pipes

• DayPipe
  • Sélecteur : | day
• PhonePipe
  • Sélecteur : | phone

Map

Composants

• MapComponent
  • Sélecteur : app-map

Models

• Equipment
• typeStructureEnum
• Weekday
• Address
• Day
• GeoJson
• OpeningDay
• PersonalOffer
• Structure
• Time
• Week

Repositories

• GeoJsonRepository

Structure

Composants

• CardComponent
  • Sélecteur : app-card
• StructureListSearchComponent
  • Sélecteur : app-structure-list-search
• StructureListComponent
  • Sélecteur : app-structure-list
• StructureDetailsComponent
  • Sélecteur : app-structure-details

Models

• Category
• Filter
• Module

Repositories

• SearchRepository
• StructureRepository

Gestion des versions

Afin de maintenir un cycle de publication clair et de favoriser la rétrocompatibilité, la dénomination des versions suit la spécification décrite par la Gestion sémantique de version

Les versions disponibles ainsi que les journaux décrivant les changements apportés sont disponibles depuis la page des Releases.

Licence

Voir le fichier LICENSE.md du dépôt.