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
dansprojects
- 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
ettsconfig.json
pour adapter le projet au développement de la bibliothèque qui vient d'être générée dans le nouveau dossierprojects
- Créer le fichier
tsconfig.base.json
Ă la racine du projet et y copier le contenu detsconfig.json
en supprimant la propriétécompilerOptions.paths
, pour Ă©viter une duplication il est possible de faire en sorte quetsconfig.json
Ă©tendetsconfig.base.json
en ajoutant seulement la propriétécompilerOptions.paths
- Optionnellement, il est possible d'adapter le code généré dans
angular.json
ettsconfig.json
, ainsi que l'arborescence dans le dossierprojects
afin d'ajouter le@
manquant pour correspondre au cheminprojects/@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
dansdist
, soit exécuter la commandenpx ng test @gouvfr-anct/mediation-numerique
directement dans le dossierprojects/@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/
outest/
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
avecX.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 unpush
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
- Les Ă©tapes du workflow
- 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
- met Ă jour la version dans le fichier
- 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
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
etmax
-
InitialPosition : Configuration de la position initiale de la carte par la
latitude
et lalongitude
-
MarkerType : Configuration des types de marqueurs
structure
,mdm
,conseillerFrance
,user
-
GeojsonService : Repository disposant des méthodes
getMDMGeoJson
etgetTownshipCoord
-
GeometryPolygonConfiguration : Configuration d'une forme de type
- Structure
-
SearchService : Repository disposant des méthodes
getCategoriesAccompaniment
,getCategoriesOthers
,getCategoriesTraining
etgetIndex
-
StructureService : Repository disposant des méthodes
getStructure
etsendMailOnStructureError
-
SearchService : Repository disposant des méthodes
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
- Map
- Structure
Éléments disponibles
Shared
Composants
-
ButtonComponent
- SĂ©lecteur :
app-button
- SĂ©lecteur :
-
SvgIconComponent
- SĂ©lecteur :
app-svg-icon
- SĂ©lecteur :
-
TextInputModalComponent
- SĂ©lecteur :
app-text-input-modal
- SĂ©lecteur :
Directives
-
ModalOutsideDirective
- SĂ©lecteur :
[clickOutside]
- SĂ©lecteur :
-
TooltipDirective
- SĂ©lecteur :
[app-tooltipDirective]
- SĂ©lecteur :
Pipes
Map
Composants
-
MapComponent
- SĂ©lecteur :
app-map
- SĂ©lecteur :
Models
- Equipment
- typeStructureEnum
- Weekday
- Address
- Day
- GeoJson
- OpeningDay
- PersonalOffer
- Structure
- Time
- Week
Repositories
Structure
Composants
-
CardComponent
- SĂ©lecteur :
app-card
- SĂ©lecteur :
-
StructureListSearchComponent
- SĂ©lecteur :
app-structure-list-search
- SĂ©lecteur :
-
StructureListComponent
- SĂ©lecteur :
app-structure-list
- SĂ©lecteur :
-
StructureDetailsComponent
- SĂ©lecteur :
app-structure-details
- SĂ©lecteur :
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.