diff --git a/CODING.md b/CODING.md new file mode 100644 index 00000000..34cfd52d --- /dev/null +++ b/CODING.md @@ -0,0 +1,37 @@ +# CODING.md + +Mémo de code pour la bibliothèque `geoportal-access-lib`. + +## Périmètre + +- Bibliothèque JavaScript ESM dédiée à l'accès aux services Géoplateforme +- Point d'entrée public: [src/Gp.js](src/Gp.js) +- Artefacts principaux: [dist/GpServices.js](dist/GpServices.js), [dist/GpServices-src.js](dist/GpServices-src.js) et [dist/GpServices-map.js](dist/GpServices-map.js) + +## Règles de code + +- Node.js `>=20` +- Indentation à 4 espaces +- Guillemets doubles +- Point-virgule obligatoire +- Espace avant les parenthèses de fonction +- Accolades explicites +- `var` reste autorisé dans le code historique du dépôt +- La JSDoc doit rester cohérente avec toute API publique modifiée +- Conserver le style local des fichiers existants + +## Vérifications + +- `npm run eslint` +- `npm run build` +- `npm run build:prod` +- `npm run build:dev` +- `npm run test` +- `npm run test:serve` +- `npm run sample:serve` +- `npm run doc:serve` + +## Références + +- Installation, build, exemples et tests: [COMPILE.md](COMPILE.md) +- Branches, commits et PR: [CONTRIBUTING.md](CONTRIBUTING.md) \ No newline at end of file diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index cad9b970..dcc27c60 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -2,37 +2,33 @@ Si vous souhaitez contribuer au code de la bibliothèque d'accès aux ressources du Géoportail, voici quelques conseils pratiques et règles à suivre. - ## Ouverture d'un ticket (issue) Vous pouvez ouvrir un ticket dans les situations suivantes : * Signaler une erreur que vous ne pouvez pas résoudre vous-même -* Discuter d'un sujet ou d'une idée relatives au projet -* Proposer une nouvelle fonctionnalité ou une évolution de fonctionnalité - -Votre ticket est ensuite pris en compte par les membres de l'équipe ou de la communauté. Et une action peut vous être demandée telle qu'**ouvrir une Pull Request** afin de contribuer... +* Discuter d'un sujet ou d'une idée relative au projet +* Proposer une nouvelle fonctionnalité ou l'évolution d'une fonctionnalité +Votre ticket est ensuite pris en compte par les membres de l'équipe ou de la communauté. Une action peut alors vous être demandée, par exemple l'ouverture d'une **pull request** afin de contribuer. ## Ouvrir une pull request (PR) Une pull request vous permet de soumettre une proposition d'évolution du code source à l'équipe en charge du projet. Voici comment soumettre une **pull request** ! - ### On «fork» le projet -- Créez un `fork` du projet sur le Github. -- Cloner le en local. Ce `dépôt distant` sur le Github s'appelle `origin`. -- Ajoutez le dépôt d'origine en tant que `dépôt distant` avec le mot cléf : `upstream` (cf. https://help.github.com/articles/configuring-a-remote-for-a-fork/). -- Si vous avez créé votre `fork` il y a quelque temps, assurez-vous de récupérer les modifications dans votre dépôt local (cf. https://help.github.com/articles/syncing-a-fork/). -- Récupérez les modification le plus souvent possible de "upstream" afin d'être le plus à jour possible, de sorte que lorsque vous soumettez votre demande (PR), les conflits de fusion seront plus faciles à résoudre ! - +* Créez un `fork` du projet sur GitHub. +* Clonez-le en local. Ce `dépôt distant` sur GitHub s'appelle `origin`. +* Ajoutez le dépôt d'origine comme `dépôt distant` nommé `upstream` (cf. https://help.github.com/articles/configuring-a-remote-for-a-fork/). +* Si vous avez créé votre `fork` il y a quelque temps, assurez-vous de récupérer les modifications dans votre dépôt local (cf. https://help.github.com/articles/syncing-a-fork/). +* Récupérez le plus souvent possible les modifications de `upstream` afin d'être à jour et de réduire les conflits de fusion lorsque vous soumettez votre PR. ### On code... -- Créez une `nouvelle branche` pour travailler. Nommez la par exemple avec le nom de la fonctionnalité à implementer (ex. feature-tests-myfunction) ou celui de l'issue qu'elle vise à résoudre (ex. feature-issue-xx) +* Créez une `nouvelle branche` pour travailler. Nommez-la par exemple avec le nom de la fonctionnalité à implémenter (ex. `feature-tests-myfunction`) ou celui de l'issue qu'elle vise à résoudre (ex. `feature-issue-xx`). -- Dans le répertoire local du projet, installez les dépendances du projet : +* Dans le répertoire local du projet, installez les dépendances du projet : ``` bash npm install @@ -40,67 +36,64 @@ npm install cf. *COMPILE.md* pour plus d'infos. +* Écrivez, testez et corrigez votre `code` sur votre copie locale de votre fork. -- Ecrivez testez, corrigez votre `code` sur votre copie locale de votre fork. - -Les commandes : +Les commandes suivantes génèrent les différents bundles dans `dist/` : ``` bash -gulp build [--production] -gulp publish +npm run build +npm run build:prod +npm run build:dev ``` -Vous permettent de générer les binaires de la bibliothèque d'accès et de les placer dans le répertoire *dist/*. Des pages html de test d'utilisation sont dans le répertoire *samples/*. Elles utilisent les binaires présents dans le répertoire *dist/*. +Des pages HTML de test d'utilisation sont dans le répertoire *samples/*. Elles utilisent les binaires présents dans le répertoire *dist/*. La commande : ``` bash -gulp server-connect +npm run sample:serve ``` -Lance un navigateur avec les pages d'exemples servies sur l'adresse http://localhost:9001 - +Lance un navigateur avec les pages d'exemples servies sur l'adresse http://localhost:9001. -- Suivez les règles de codage du projet. Elles sont définies dans les fichiers : .jscsrc (style et convention de codage) et .jshintrc (syntaxe javascript). Vous pouvez vérifier le bon respect de ces règles en lançant la tache : +* Suivez les règles de codage du projet. Elles sont définies par ESLint dans le fichier `.eslintrc.json`. Vous pouvez vérifier le bon respect de ces règles en lançant la tâche : ``` bash -gulp check +npm run eslint ``` -- Vérifiez, ajoutez ou adaptez les tests si nécessaire. +* Vérifiez, ajoutez ou adaptez les tests si nécessaire. * Les tests unitaires sont dans le répertoire *test/spec/* * Les tests fonctionnels sont dans le répertoire *test/spec-functional/* * Les pages d'exemples sont dans le répertoire *samples/* -- Ajoutez ou modifiez la `documentation` si nécessaire. Si votre PR apporte une modification d'interface à la bibliothèque, mettez à jour la jsDoc en conséquences et vérifiez quelle est bien prise en compte. +* Ajoutez ou modifiez la `documentation` si nécessaire. Si votre PR apporte une modification d'interface à la bibliothèque, mettez à jour la JSDoc en conséquence et vérifiez qu'elle est bien prise en compte. * La jsDoc publique des fonctions de la bibliothèque est rassemblée dans le fichier *src/Services/Services.js*, * La jsDoc des classes publiques de réponse dans : *src/Services//Response/model/*.js -La commande +La documentation générée est servie depuis le répertoire `jsdoc/`. ``` bash -gulp doc +npm run doc:serve ``` -Vous permet de générer la jsDoc du projet dans le répertoire *target/doc/* +Vous permet de consulter la documentation du projet dans votre navigateur. -- Rajoutez vous dans le fichier [CONTRIBUTORS.md](CONTRIBUTORS.md]) si vous n'y êtes pas déjà. +* Ajoutez-vous dans le fichier [CONTRIBUTORS.md](CONTRIBUTORS.md) si vous n'y êtes pas déjà. -- `Squash` vos commits en un seul avec le `rebase interactif` (cf. https://help.github.com/articles/interactive-rebase) ou via d'autre méthodes (cf. https://gist.github.com/patik/b8a9dc5cd356f9f6f980 par exemple) - -- Poussez cette branche sur votre dépôt, sur le dépôt marqué `origin`. +* Squashez vos commits en un seul avec le `rebase interactif` (cf. https://help.github.com/articles/interactive-rebase) ou via d'autres méthodes (cf. https://gist.github.com/patik/b8a9dc5cd356f9f6f980, par exemple). +* Poussez cette branche sur votre dépôt, sur le dépôt marqué `origin`. ### On soumet une PR... -- De votre `fork`, ouvrez une demande de `pull request` sur cette branche (cf. https://help.github.com/articles/creating-a-pull-request/). Et ciblez sur la branche `develop` du dépôt d'origine... -- Référencez tous les problèmes ainsi que la documentation sur votre PR. -- Utilisez dans vos `commit` des fonctionnalités de GitHub (ex. "Fix #37."). -- Si le responsable demande des modifications supplémentaires, il suffit de les pousser vers votre branche locale, la `pull request` se met à jour automatiquement. -- Une fois que la `pull request` est approuvée, les responsables du projet effectueront le merge (cf. https://help.github.com/articles/merging-a-pull-request/). - +* Depuis votre `fork`, ouvrez une demande de `pull request` sur cette branche (cf. https://help.github.com/articles/creating-a-pull-request/) en la ciblant sur la branche `develop` du dépôt d'origine. +* Référencez tous les problèmes ainsi que la documentation dans votre PR. +* Utilisez dans vos `commit` les fonctionnalités de GitHub (ex. `Fix #37.`). +* Si le responsable demande des modifications supplémentaires, il suffit de les pousser sur votre branche locale ; la `pull request` se met à jour automatiquement. +* Une fois que la `pull request` est approuvée, les responsables du projet effectueront le merge (cf. https://help.github.com/articles/merging-a-pull-request/). ## Liens utiles @@ -118,5 +111,5 @@ avec les liens les plus utiles : https://help.github.com/articles/interactive-rebase Un exemple de contribution sur un projet (en français) : -https://git-scm.com/book/fr/v2/GitHub-Contribution-%C3%A0-un-projet +https://git-scm.com/book/fr/v2/GitHub-Contribution-%C3%A0-un-projet diff --git a/CONTRIBUTORS.md b/CONTRIBUTORS.md index 919f3be3..8a20f5ab 100644 --- a/CONTRIBUTORS.md +++ b/CONTRIBUTORS.md @@ -1,7 +1,7 @@ Le fichier [CONTRIBUTING.md](CONTRIBUTING.md) définit les règles et pratiques pour contribuer au projet geoportal-access-lib. Les personnes suivantes ont contribué à ce projet : -# Equipe de développement +# Équipe de développement * [lboulanger](https://github.com/lboulanger) * [lowzonenose](https://github.com/lowzonenose) @@ -15,5 +15,4 @@ Le fichier [CONTRIBUTING.md](CONTRIBUTING.md) définit les règles et pratiques * [ThomasG77](https://github.com/ThomasG77) * [sylvainpolletvillard](https://github.com/sylvainpolletvillard) - * [jfgigand](https://github.com/jfgigand) - + * [jfgigand](https://github.com/jfgigand) \ No newline at end of file diff --git a/DEPENDENCIES.md b/DEPENDENCIES.md new file mode 100644 index 00000000..c8cc185e --- /dev/null +++ b/DEPENDENCIES.md @@ -0,0 +1,21 @@ +# Dépendances tierces + +Ce fichier recense les dépendances runtime principales du projet et leur licence. + +## @xmldom/xmldom + +- Rôle: parser et sérialiser du XML via DOM +- Licence: MIT +- Source: https://github.com/xmldom/xmldom + +## es6-promise + +- Rôle: polyfill de `Promise` pour compatibilité navigateur et anciens environnements +- Licence: MIT +- Source: https://github.com/stefanpenner/es6-promise + +## node-fetch + +- Rôle: implémentation `fetch` côté Node.js +- Licence: MIT +- Source: https://github.com/node-fetch/node-fetch diff --git a/geoportal-access-lib-3.4.7-pr-94.tgz b/geoportal-access-lib-3.4.7-pr-94.tgz deleted file mode 100644 index 7587bbe6..00000000 Binary files a/geoportal-access-lib-3.4.7-pr-94.tgz and /dev/null differ