From 3915048ab883aac5315acfb25f33465c213d2791 Mon Sep 17 00:00:00 2001
From: Guillaume WANG <guillaume.wang@polytechnique.edu>
Date: Fri, 30 Nov 2018 02:57:12 +0100
Subject: [PATCH] clarify README and CONTRIBUTING more
---
CONTRIBUTING.md | 6 ++++-
README.md | 66 ++++++++++++++++++++++++++-----------------------
package.json | 1 +
3 files changed, 41 insertions(+), 32 deletions(-)
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 3eb6017..1910442 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -143,7 +143,11 @@ Par cette interface admin, on a accès :
## Notes sur javascript
-La syntaxe adoptée est JavaScript ES6, un standard moderne (2015) de JavaScript.
+La syntaxe adoptée est JavaScript ES6, un standard moderne (2015) de JavaScript. Node ne comprend pas ES6, mais ES5 (un tout petit peu plus que ES5 en fait).
+
+On utilise Webpack pour transpiler les fichiers source [`src/`](./src/) en un [`bundle.js`](./build/bundle.js) qui, lui, suit la syntaxe ES5 compatible avec Node.
+Pour lancer une transpilation, `npm run build` (mode production) ou `npm run dev` (mode développement).
+La commande `webpack` est configurable dans le fichier `webpack.config.js`.
### `import` vs `require`
Le standard moderne permet d'importer des dépendances en utilisant le mot-clé `import`, ce que le serveur Node.js ne comprend pas puisque la version 8 de Node ne comprend que le standard ES5 (2009), qui gère les imports avec `require()`.
diff --git a/README.md b/README.md
index 4e207d1..0252299 100644
--- a/README.md
+++ b/README.md
@@ -7,15 +7,16 @@ Ce dépôt contient le _backend_ de Sigma, le successeur de Frankiz, un site ét
À terme, ce projet doit tourner sur un serveur du BR et servir d'API à un _frontend_ React *au code séparé et documenté séparément* toute les données nécessaires à son bon fonctionnement (authentification, appartenance à un groupe, droits de visibilité...). Le dépôt pour le serveur front se trouve ici : <https://gitlab.binets.fr/br/sigma-frontend> (on l'appellera indifféremment serveur front, front ou frontend...)
-## Obtenir une copie du projet en mode développement
-
-Cloner le dépôt :
+Pour obtenir une copie du projet, cloner le dépôt par :
```bash
git clone git@gitlab.binets.fr:br/sigma-backend.git
# ou
git clone https://gitlab.binets.fr/br/sigma-backend.git
```
+## Démarrer le serveur (en mode développement)
+
+### Installer les dépendances
Installer les dépendances (spécifiées dans `package.json`) :
```bash
npm install
@@ -31,6 +32,8 @@ Installer PostgreSQL :
```bash
sudo apt install postgresql
```
+
+### Setup la BDD PostgreSQL
Créer un rôle PostgreSQL "sigma" :
```bash
sudo -u postgres -s
@@ -55,16 +58,17 @@ knex migrate:latest
knex seed:run
```
-Dire à webpack de build le projet (build le bundle `main.js`) :
+### Démarrer le serveur
+Dire à webpack de build le projet (build le bundle `./build/bundle.js`) :
```bash
npm run dev # en mode developpement
# ou
npm run build # en mode production
```
-Lancer un serveur express/node (nodemon en fait) :
+Lancer un serveur express/node :
```bash
-npm run start #see (package.json).scripts
+npm run start # ou le raccourci: npm start
```
Comme indiqué dans src/index.js, ceci lance un serveur servant l'application express sur le port 3000.
@@ -92,9 +96,11 @@ Ca a un rapport avec NODE_ENV ?
## Dépendances *npm*
-On utilise un serveur Node.js avec [express.js](https://expressjs.com/) ; il est configuré dans [`app.ts`](../src/app.ts) puis lancé sur le port 3000 dans [`index.ts`](../src/index.ts).
+On utilise un serveur node.js avec [express.js](https://expressjs.com/). [^server]
Utiliser Node.js permet d'utiliser facilement [*npm*](https://www.npmjs.com/) (Node Package Manager). Une "dépendance" est un package utilisé dans le projet.
+[^server]: il est configuré dans [`app.ts`](./src/app.ts) puis lancé sur le port 3000 dans [`index.ts`](./src/index.ts).
+
On trouve la liste des dépendances dans [`package.json`](./package.json). Express est un exemple de dépendance normale, utilisée en production ; nodemon et ESLint (voir infra) sont des dépendances dev (`devDependencies`), utilisées seulement en mode développement.
Les dépendances s'installent avec `npm install`. Cette commande a deux comportements possibles selon la valeur de la variable `NODE_ENV` (vérifier avec la commande `echo "$NODE_ENV"`):
@@ -116,6 +122,22 @@ Les dépendances principales utilisées sont
- *webpack*, qui compile et optimise tout le code source javascript en un `bundle.js`,
- *ESlint*, pour le développement, outil de vérification syntaxique.
+## Scripts
+
+Les scripts sont des instructions en ligne de commande que l'on peut faire tourner avec la commande `npm run`. Ce sont des raccourcis pour gagner du temps sur des opérations un peu longues. Ils sont définis dans [`package.json`](./package.json).
+
+Les plus importants sont détaillées ci-dessous :
+- `npm run build` : transpiler avec Webpack, en mode production
+- `npm run dev` : idem, mais en mode développement
+- `npm run watch` : idem, mais retranspile automatiquement dès que le code est modifié.
+- `npm run start` : lancer un serveur Node avec nodemon
+- `npm run doc` : générer la doc JSDoc
+- `npm run lint` : vérifier la syntaxe de tous les fichiers .js et .ts du dossier src/
+
+`npm run start` démarre en fait le serveur buildé [`build/bundle.js`](build/bundle.js) avec [nodemon](https://nodemon.io/), un outil de dév qui le redémarre automatiquement après toute modification *du bundle*.
+
+Donc, lancer `npm run watch` dans un terminal et `npm run start` dans un autre permet de rebuilder **et** relancer automatiquement le serveur, après toute modification *du code source*.
+
## Configuration
L'API est conçue pour êtes modulaire et pour fonctionner dans plusieurs environnements.
@@ -192,41 +214,23 @@ Le panneau d'administration sert (ou plutôt, servira à terme) à accéder dire
L'application Voyager, accessible à `/adminview/voyager`, permet de visualiser le « graphe » sous-jacent à la structure de l'API.
-## GraphQL Playground
+### GraphQL Playground
+
+== Attention, comme tout GraphQL Playground est géré directement par le package apollo-server-express, les requêtes dans le Playground **ne sont pas** soumises au mêmes règles de permission que dans adminview. (D'ailleurs, `/graphql` n'est même pas un sous-path de `/adminview`.) ==
Accéder via un navigateur à `/graphql` renvoie l'application GraphQL Playground.
-Il s'agit du même `/graphql` que l'_endpoint_ de l'API, mais le serveur est configuré de sorte à renvoyer Playground lorsqu'il détecte un accès via navigateur. Comme tout GraphQL Playground est géré directement par la package graphql, les requêtes dans le Playground sont soumises au mêmes permissions que dans l'API GraphQL [^doute]. GraphQL Playground est désactivé en production.
+Il s'agit du même `/graphql` que l'_endpoint_ de l'API, mais le serveur est configuré de sorte à renvoyer Playground lorsqu'il détecte un accès via navigateur. Les requêtes dans le Playground sont cependant soumises au mêmes permissions que dans l'API GraphQL [^doute]. GraphQL Playground est désactivé en production.
[^doute]: euuuuh à vérifier...
-## Scripts
-Les scripts sont des instructions en ligne de commande que l'on peut faire tourner avec la commande `npm run`. Ce sont des raccourcis pour gagner du temps sur des opérations un peu longues. Ils sont définis dans [`package.json`](../package.json).
-
-Les plus importants sont détaillées ci-dessous (ne pas oublier `npm install` déjà mentionné plus tôt) :
-
-On utilisera Webpack pour transpiler le fichier source [`src/index.js`](../src/index.js) en [`build/bundle.js`](../build/bundle.js) qui est suit la syntaxe ES5 compatible Node. Pour ça, on utilise :
-
-* `npm run build` qui exécute la commande `webpack` avec le fichier de configuration `webpack.config.js`, ou
-* `npm run watch` qui recompile automatiquement dès que le code est modifié.
-
-### Démarrer le serveur
-
-Pour faire tourner le serveur, lancer
-
- npm start
-
-démarre le serveur compilé [`build/bundle.js`](build/bundle.js) avec [nodemon](https://nodemon.io/), outil dév, et le redémarre automatiquement après modification.
+## Documentation
-Donc, lancer `npm run watch` dans un terminal et `npm start` dans un autre permet de recompiler le serveur __et__ le relance automatiquement.
+La documentation détaillée du projet est [ici](./doc/index.html). Elle a été compilée avec [JSDoc](http://usejsdoc.org/index.html) sous format hmtl selon le fichier de configuration [`configfile_doc.json`](./configfile_doc.json) à la racine du projet.
Le script pour faire tourner [JSDoc](http://usejsdoc.org/index.html) et régénérer la documentation est : `npm run doc`
-## Documentation
-
-La documentation détaillée du projet est [ici](./doc/index.html). Elle a été compilée avec [JSDoc](http://usejsdoc.org/index.html) sous format hmtl selon le fichier de configuration [`configfile_doc.json`](../configfile_doc.json) à la racine du projet.
-
Les fichiers compilés se situent dans [`doc`](.) avec leurs fichiers image. Par nature de l'outil JSDoc il est facile de documenter en détail des fonctions .js mais plus compliqué de documenter un fichier.
A la fin de ce fichier JSDoc rajoute les commentaires placés dans chacun des fichiers et des hyperliens pour y accéder.
diff --git a/package.json b/package.json
index 3ef2d48..3400d42 100644
--- a/package.json
+++ b/package.json
@@ -7,6 +7,7 @@
"dev": "webpack --mode development",
"watch": "webpack --watch --mode development",
"start": "nodemon --watch build ./build/bundle.js",
+ "start_prod": "node ./build/bundle.js",
"doc": "jsdoc --configure configfile_doc.json",
"lint": "eslint --ext .js --ext .ts src/ "
},
--
GitLab