Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/anct-cartographie-nationale/mediation-numerique

📚 Bibliothèque pour la cartographie de l’offre de médiation numérique.
https://github.com/anct-cartographie-nationale/mediation-numerique

anct angular betagouv bibliotheque cartographie gouvernement mediation-numerique

Last synced: 20 days ago
JSON representation

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

Awesome Lists containing this project

README 

        
# 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](#à-propos)

- 📦 [Prérequis](#prérequis)

- 🚀 [Installation](#installation)

- 🛠️ [Utilisation](#utilisation)

- 🤝 [Contribution](#contribution)

- 🏗️ [Construit avec](#construit-avec)

- đź“š [Documentation](#documentation)

- 🏷️ [Gestion des versions](#gestion-des-versions)

- đź“ť [Licence](#licence)



## Prérequis



- [Git](https://git-scm.com/) : Système de contrôle de versions distribué d'un ensemble de fichiers

- [Node](https://nodejs.org/) : Environnement d'exécution pour Javascript

- [Yarn](https://yarnpkg.com/) : Gestionnaire de paquets pour les produits développés dans des environnements Node



> Node et Yarn peuvent être installés via [nvm](https://github.com/nvm-sh/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](https://github.com/anct-cartographie-nationale/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](https://typicode.github.io/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` :



```bash

npx husky install

```



Rendre exécutable les fichiers qui contiennent les hooks :



```bash

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](https://kapeli.com/cheat_sheets/Conventional_Commits.docset/Contents/Resources/Documents/index)

- 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](https://www.conventionalcommits.org/fr)



#### 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](https://docs.github.com/en/[email protected]/authentication/managing-commit-signature-verification/about-commit-signature-verification)

- Les utilisateurs de [keybase](https://keybase.io/) peuvent [signer leurs commits avec leur clé GPG sur Keybase](https://stephenreescarter.net/signing-git-commits-with-a-keybase-gpg-key/)



### 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](https://github.com/anct-cartographie-nationale/mediation-numerique/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](https://github.com/anct-cartographie-nationale/client-base/blob/main/.prettierrc.json)

  - Que le code écrit en TypeScript respecte les conventions décrites par les [règles ESLint](https://github.com/anct-cartographie-nationale/client-base/blob/main/.eslintrc.json)

  - Que les messages des commits suivent le standard Ă©tabli par [Conventional Commits](https://www.conventionalcommits.org/fr)

- Une fois les développements terminés, il faut créer une [pull request](https://github.com/anct-cartographie-nationale/mediation-numerique/pulls) 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)](https://semver.org/lang/fr/), alors il faut créer une [pull request](https://github.com/anct-cartographie-nationale/mediation-numerique/pulls) vers la branche `main`, il ne faut pas le faire si ce n'est pas le cas.



## Construit avec



### langages & Frameworks



- [TypeScript](https://www.typescriptlang.org/) est un langage open source construit Ă  partir de JavaScript

- [Angular](https://angular.io/) est une boîte à outils open source pour construire des clients web



### Outils



#### CLI



- [Jest](https://jestjs.io/) est une boîte à outils pour écrire des tests automatisés en JavaScript

- [Eslint](https://eslint.org/) est un analyseur statique de JavaScript avec les plugins suivants :

- [Prettier](https://prettier.io/) est un magnificateur de code source en JavaScript



#### CI



- [Github Actions](https://docs.github.com/en/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](https://github.com/anct-cartographie-nationale/mediation-numerique/actions/)

- Secrets du dépôt :

  - `NODE_AUTH_TOKEN` : Clé d'accès NPM pour publier sur l'organisation [@gouvfr-anct](https://www.npmjs.com/org/gouvfr-anct)



#### DĂ©ploiement



- [npm](https://www.npmjs.com/) est le registre de référence pour les paquets Node.

  - Organisation : [@gouvfr-anct](https://www.npmjs.com/org/gouvfr-anct)

  - Paquet : [@gouvfr-anct/mediation-numerique](https://www.npmjs.com/package/@gouvfr-anct/mediation-numerique)



## Documentation



### Table des matières



- [Mise en place](#mise-en-place)

  - [Configurations](#configurations)

  - [Modules](#modules)

- [Éléments disponibles](#éléments-disponibles)

  - [Shared](#shared)

  - [Map](#map)

  - [Structure](#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](./src/lib/configurations/geometry-polygon.configuration.ts) : Configuration d'une forme de type `FeatureCollection` Ă  afficher sur la carte

  - [ZoomLevel](./src/lib/configurations/zoom-level.configuration.ts) : Configuration des niveaux de zooms `min`, `regular`, `userPosition` et `max`

  - [InitialPosition](./src/lib/configurations/initial-position.configuration.ts) : Configuration de la position initiale de la carte par la `latitude` et la `longitude`

  - [MarkerType](./src/lib/configurations/marker-type.configuration.ts) : Configuration des types de marqueurs `structure`, `mdm`, `conseillerFrance`, `user`

  - [GeojsonService](./src/lib/map/repositories/geo-json.repository.ts) : Repository disposant des méthodes `getMDMGeoJson` et `getTownshipCoord`

- Structure

  - [SearchService](./src/lib/structure/repositories/search.repository.ts) : Repository disposant des méthodes `getCategoriesAccompaniment`, `getCategoriesOthers`, `getCategoriesTraining` et `getIndex`

  - [StructureService](./src/lib/structure/repositories/structure.repository.ts) : 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](./shared/src/lib/components/button/button.module.ts)

  - [SvgIconModule](./shared/src/lib/components/svg-icon/svg-icon.component.ts)

  - [TextInputModalModule](./shared/src/lib/components/text-input-modal/text-input-modal.module.ts)

  - [ModalModule](./shared/src/lib/directives/modal/modal.module.ts)

  - [TooltipModule](./shared/src/lib/directives/tooltip/tooltip.module.ts)

  - [DayModule](./shared/src/lib/pipes/day/day.module.ts)

  - [PhoneModule](./shared/src/lib/pipes/phone/phone.pipe.ts)

- Map

  - [MapModule](./src/lib/map/components/map.module.ts)

- Structure

  - [StructureModule](./src/lib/structure/modules/structure.module.ts)



### Éléments disponibles



#### Shared



##### Composants



- [ButtonComponent](./shared/src/lib/components/button/button.component.ts)

  - SĂ©lecteur : `app-button`

- [SvgIconComponent](./shared/src/lib/components/svg-icon/svg-icon.component.ts)

  - SĂ©lecteur : `app-svg-icon`

- [TextInputModalComponent](./shared/src/lib/components/text-input-modal/text-input-modal.component.ts)

  - SĂ©lecteur : `app-text-input-modal`



##### Directives



- [ModalOutsideDirective](./shared/src/lib/directives/modal/modalOutside.directive.ts)

  - SĂ©lecteur : `[clickOutside]`

- [TooltipDirective](./shared/src/lib/directives/tooltip/tooltip.directive.ts)

  - SĂ©lecteur : `[app-tooltipDirective]`



##### Pipes



- [DayPipe](./shared/src/lib/pipes/day/day.pipe.ts)

  - SĂ©lecteur : `| day`

- [PhonePipe](./shared/src/lib/pipes/phone/phone.pipe.ts)

  - SĂ©lecteur : `| phone`



#### Map



##### Composants



- [MapComponent](./src/lib/map/components/map.component.ts)

  - SĂ©lecteur : `app-map`



##### Models



- [Equipment](./src/lib/map/models/enum/equipment.enum.ts)

- [typeStructureEnum](./src/lib/map/models/enum/typeStructure.enum.ts)

- [Weekday](./src/lib/map/models/enum/weekday.enum.ts)

- [Address](./src/lib/map/models/address.model.ts)

- [Day](./src/lib/map/models/day.model.ts)

- [GeoJson](./src/lib/map/models/geojson.model.ts)

- [OpeningDay](./src/lib/map/models/openingDay.model.ts)

- [PersonalOffer](./src/lib/map/models/personalOffer.model.ts)

- [Structure](./src/lib/map/models/structure.model.ts)

- [Time](./src/lib/map/models/time.model.ts)

- [Week](./src/lib/map/models/week.model.ts)



##### Repositories



- [GeoJsonRepository](./src/lib/map/repositories/geo-json.repository.ts)



#### Structure



##### Composants



- [CardComponent](./src/lib/structure/components/card/card.component.ts)

  - SĂ©lecteur : `app-card`

- [StructureListSearchComponent](./src/lib/structure/components/search/structure-list-search.component.ts)

  - SĂ©lecteur : `app-structure-list-search`

- [StructureListComponent](./src/lib/structure/components/structure-list/structure-list.component.ts)

  - SĂ©lecteur : `app-structure-list`

- [StructureDetailsComponent](./src/lib/structure/components/structure-details/structure-details.component.ts)

  - SĂ©lecteur : `app-structure-details`



##### Models



- [Category](./src/lib/structure/models/category.model.ts)

- [Filter](./src/lib/structure/models/filter.model.ts)

- [Module](./src/lib/structure/models/module.model.ts)



##### Repositories



- [SearchRepository](./src/lib/structure/repositories/search.repository.ts)

- [StructureRepository](./src/lib/structure/repositories/structure.repository.ts)



## 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](https://semver.org/lang/fr/)



Les versions disponibles ainsi que les journaux décrivant les changements apportés sont disponibles depuis [la page des Releases](https://github.com/anct-cartographie-nationale/mediation-numerique/releases).



## Licence



Voir le fichier [LICENSE.md](./LICENSE.md) du dépôt.