# Contribution ## Table des matiĂšres - 📩 [PrĂ©requis](#prĂ©requis) - 🚀 [Installation](#installation) - đŸ› ïž [Utilisation](#utilisation) - đŸ€ [Contribution](#contribution) - đŸ—ïž [Construit avec](#construit-avec) ## PrĂ©requis ### Outils - [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 ### Mise en place des sources et des dĂ©pendances Cloner le dĂ©pĂŽt en local ```bash git clone git@github.com:anct-cartographie-nationale/mednum-cli.git ``` Aller dans le dossier du projet pour installer les dĂ©pendances ```bash cd mednum-cli yarn ``` ### Installer Husky [Husky](https://typicode.github.io/husky) est un outil de gestion des hooks git pour effectuer des tĂąches automatiques ```bash yarn husky install ``` Rendre exĂ©cutable les fichiers qui contiennent les hooks : ```bash chmod a+x .husky/commit-msg chmod a+x .husky/pre-commit ``` ### Configurer l'environnement Le fichier d'environnement `.env` contient les variables d'environnements nĂ©cessaires Ă  l'exĂ©cution de la commande `mednum publier` Pour faciliter la mise en place du fichier d'environnement, vous pouvez copier le fichier [.env.example](.env.example) et le renommer en `.env`. ⚠ Le fichier `.env` est susceptible de contenir des donnĂ©es sensibles, il ne doit jamais ĂȘtre traquĂ© par un gestionnaire de version. ⚠ Le fichier `env.example` est une aide pour la mise en place du fichier `.env`, il est public et ne doit pas contenir de donnĂ©es sensibles. Configurez les variables d'environnements attendus dans le fichier `.env` : #### `DATA_GOUV_API_URL` L'URL de l'API data.gouv, il est recommandĂ© d'utiliser l'API de dĂ©mo pour le dĂ©veloppement : https://demo.data.gouv.fr/api/1 #### `DATA_GOUV_API_KEY` La clĂ© d'API qui permet Ă  la commande d'effectuer des requĂȘtes sur l'API nĂ©cessitant une authentification en votre nom. Pour obtenir une clĂ© d'API, vous devez crĂ©er un compte sur [demo.data.gouv.fr](https://demo.data.gouv.fr/fr/). Une fois connectĂ©, rendez-vous sur [votre profil dans le menuAdministration](https://demo.data.gouv.fr/fr/admin/me/). En bas Ă  gauche de la page, vous trouverez un encart intitulĂ© `ClĂ© d'API`. Il vous suffit de copier la clĂ© et de la coller comme valeur dans le fichier `.env` #### `DATA_GOUV_REFERENCE_TYPE` Il existe deux moyens de publier des jeux de donnĂ©s sur data.gouv ; vous pouvez le faire en votre propre nom ou au nom d'une organisation. Cette variable permet d'indiquer le type de publication : - La valeur `owner` signifie que vous publiez en votre propre nom. - La valeur `organization` signifie que vous publiez au nom d'une organisation. #### `DATA_GOUV_REFERENCE_ID` Vous devez indiquer l'identifiant de votre compte si vous avez choisi le type `owner` ou l'id de l'organisation si vous avez choisi le type `organization`. - Retrouvez l'id de votre compte en vous rendant sur la page d'[Administation](https://demo.data.gouv.fr/fr/admin/) de votre compte. - Appuyez sur la touche `F12` pour afficher l'inspecteur de votre navigateur et observez le moniteur de rĂ©seau - [Optionnel] Effacez les requĂȘtes prĂ©sentes pour faciliter l'identification des prochaines requĂȘtes - Dans la liste Ă  gauche, cliquez sur le menu `Profil` - Une requĂȘte avec le paramĂštre `?owner=` devrait apparaitre dans le moniteur de rĂ©seau, la valeur Ă  la suite du `=` correspond Ă  l'id de votre compte - Par exemple pour `.../api/1/harvest/sources/?owner=6396e6363a1ab130371ff777&deleted=true&lang=fr&_=1674118850001`, l'id est `6396e6363a1ab130371ff777` - Retrouvez l'id d'une organisation en vous rendant sur la page d'[Administation](https://demo.data.gouv.fr/fr/admin/) de votre compte. - Dans la liste Ă  gauche, vos organisations s'affichent en dessous du menu `Profil`. - Cliquez sur l'organisation dnt vous voulez retrouver l'id. - Une fois la page administration de l'organisation, rĂ©cupĂ©rer le dernier paramĂštre de l'URL de la page : il s'agit de l'id de l'organisation - Par exemple pour `.../admin/organization/4a4fc649a5a4982f465cfa24/`, l'id est `4a4fc649a5a4982f465cfa24` ## Utilisation Ces commandes servent dans un contexte de dĂ©veloppement de l'application. ### Test Tester le projet : ```bash yarn test ``` ### Global lint Analyse statique de tous les fichiers `.ts` du projet : ```bash yarn lint.all ``` ### Staged lint Analyse statique des fichiers `.ts` qui ont Ă©tĂ© ajoutĂ©s avec la commande `git add` : ```bash yarn lint.staged ``` ### Commit lint Valider la syntaxe de l'ensemble des commits rĂ©alisĂ©s depuis la derniĂšre version commune avec la branche `main` : ```bash yarn lint.commit ``` ### Prettier check VĂ©rifier la syntaxe de l'ensemble des fichiers du projet : ```bash yarn prettier.check ``` ### Prettier Corriger la syntaxe de l'ensemble des fichiers du projet : ```bash yarn prettier ``` ### Build GĂ©nĂ©rer une version prĂȘte Ă  ĂȘtre publiĂ©e : ```bash yarn build ``` ## 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) ### 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/enterprise-server@3.5/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/) ## Construit avec ### langages & Frameworks - [TypeScript](https://www.typescriptlang.org/) est un langage open source construit Ă  partir de JavaScript ### Outils #### CLI - [Vitest](https://vitest.dev/) est une boĂźte Ă  outils pour Ă©crire des tests automatisĂ©s en JavaScript - [Eslint](https://eslint.org/) est un analyseur statique de JavaScript - [Prettier](https://prettier.io/) est un magnificateur de code source en JavaScript - [Husky](https://typicode.github.io/husky/#/) est un outil qui permet d'effectuer des vĂ©rifications automatiques avant de publier des contributions. - [Commitlint](https://github.com/conventional-changelog/commitlint) est un outil de vĂ©rification des commits suivant le [format des Commits Conventionnels](https://www.conventionalcommits.org/fr/v1.0.0/). - [Lint-staged](https://github.com/okonet/lint-staged) est un outil qui permet d'effectuer un ensemble de vĂ©rifications Ă  l'aide d'autres outils sur un ensemble de fichiers qui viennent d'ĂȘtre modifiĂ©s. #### CI/CD - [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/mednum-cli/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) - Secrets de l'environnement `demo` : - [DATA_GOUV_API_URL](#DATA_GOUV_API_URL) - [DATA_GOUV_API_KEY](#DATA_GOUV_API_KEY) - [DATA_GOUV_REFERENCE_ID](#DATA_GOUV_REFERENCE_ID) - [DATA_GOUV_REFERENCE_TYPE](#DATA_GOUV_REFERENCE_TYPE) - Secrets de l'environnement `production` : - [DATA_GOUV_API_URL](#DATA_GOUV_API_URL) - [DATA_GOUV_API_KEY](#DATA_GOUV_API_KEY) - [DATA_GOUV_REFERENCE_ID](#DATA_GOUV_REFERENCE_ID) - [DATA_GOUV_REFERENCE_TYPE](#DATA_GOUV_REFERENCE_TYPE) #### Publication sur le registre npm À chaque fusion sur la branche `main`, l'outil est publiĂ© sur [npm](https://www.npmjs.com/) - Organisation: [@gouvfr-anct](https://www.npmjs.com/org/gouvfr-anct) - Package: [@gouvfr-anct/mednum](https://www.npmjs.com/package/@gouvfr-anct/mednum) ##### Transformations et publication automatique Les workflows GitHub [validate.yml](.github%2Fworkflows%2Fvalidate.yml) et [transform-and-publish.yml](.github%2Fworkflows%2Ftransform-and-publish.yml) se chargent de transformer et de publier automatiquement les donnĂ©es : - `validate.yml` est lancĂ© Ă  chaque push sur une branche en cours de dĂ©veloppement. Les donnĂ©es sont publiĂ©es dans un [environnement de dĂ©mo de data.gouv](https://demo.data.gouv.fr/fr/organizations/cartographie-nationale-des-lieux-de-mediation-numerique/). Pour qu'une nouvelle source de donnĂ©es soit prise en compte, il faut bien penser Ă  l'ajouter dans le job `publish-to-data-gouv` : une `strategy` de type `matrix` dĂ©finie chaque `source` Ă  transformer et publier. - `release.yml` est lancĂ© Ă  chaque fusion sur `main`. Les donnĂ©es sont publiĂ©es dans [l'organisation Cartographie Nationale des lieux de mĂ©diation numĂ©rique sur data.gouv](https://data.gouv.fr/fr/organizations/cartographie-nationale-des-lieux-de-mediation-numerique/). Pour qu'une nouvelle source de donnĂ©es soit prise en compte, il faut bien penser Ă  l'ajouter dans le job `publish-to-data-gouv` : une `strategy` de type `matrix` dĂ©finie chaque `source` Ă  transformer et publier. - `daily` est lancĂ© tous les jours Ă  04:15 AM. Les donnĂ©es sont publiĂ©es dans [l'organisation Cartographie Nationale des lieux de mĂ©diation numĂ©rique sur data.gouv](https://data.gouv.fr/fr/organizations/cartographie-nationale-des-lieux-de-mediation-numerique/). Pour qu'une nouvelle source de donnĂ©es soit prise en compte, il faut bien penser Ă  l'ajouter dans le job `publish-to-data-gouv` : une `strategy` de type `matrix` dĂ©finie chaque `source` Ă  transformer et publier.