@gouvfr-anct/mediation-numerique
TypeScript icon, indicating that this package has built-in type declarations

0.0.19 • Public • Published

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

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 git@github.com: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 git@github.com: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 :

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
  • Secrets du dĂ©pĂ´t :
    • NODE_AUTH_TOKEN : ClĂ© d'accès NPM pour publier sur l'organisation @gouvfr-anct

DĂ©ploiement

Documentation

Table des matières

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

Éléments disponibles

Shared

Composants
Directives
Pipes

Map

Composants
Models
Repositories

Structure

Composants
Models
Repositories

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.

/@gouvfr-anct/mediation-numerique/

    Package Sidebar

    Install

    npm i @gouvfr-anct/mediation-numerique

    Weekly Downloads

    15

    Version

    0.0.19

    License

    SEE LICENSE IN LICENSE.md

    Unpacked Size

    2.21 MB

    Total Files

    316

    Last publish

    Collaborators

    • marc.gavanier