Create README.md

README.md

@@ -0,0 +1,187 @@
+TWELVE HEROES 
+=============
+*The digital version of the boardgame*
+--------------------------------------
+
+- [TWELVE HEROES](#twelve-heroes)
+  - [*The digital version of the boardgame*](#the-digital-version-of-the-boardgame)
+  - [**How to modify & run**](#how-to-modify--run)
+    - [1. requirements](#1-requirements)
+    - [2. Clone the repo](#2-clone-the-repo)
+    - [3. Work in your branch](#3-work-in-your-branch)
+    - [4. To run the app for tests](#4-to-run-the-app-for-tests)
+  - [**Some info about the project**](#some-info-about-the-project)
+    - [1. npm stuff](#1-npm-stuff)
+    - [2. Editor config & VS code settings](#2-editor-config--vs-code-settings)
+    - [3. ES lint](#3-es-lint)
+    - [4. Babel](#4-babel)
+    - [5. Cordova](#5-cordova)
+    - [6. Webpack](#6-webpack)
+    - [7. Git ignore](#7-git-ignore)
+    - [8. Source code](#8-source-code)
+  - [**NPM scripts**](#npm-scripts)
+    - [1. How NPM scripts work](#1-how-npm-scripts-work)
+    - [2. Description of the project npm scripts](#2-description-of-the-project-npm-scripts)
+  - [**Useful links**](#useful-links)
+    - [1. Google drive stuff](#1-google-drive-stuff)
+    - [2. Trello](#2-trello)
+
+
+
+## **How to modify & run**
+
+### 1. requirements
+   * NodeJS : >= v10.17.0
+   * npm : >= v6.11.3
+
+### 2. Clone the repo
+   * clone with your username (It will ask for your bitbucket password):  
+      `git clone https://USERNAME@bitbucket.org/jojolb/twelve-heroes.git`
+
+!  So far all the code I worked on is in the branch named "test" !
+
+### 3. Work in your branch
+   * `cd twelve-heroes`
+   * All the new code in on branch "test" so go there :  
+    `git checkout test`
+
+   * Create your own branch from this code and name it as you want :  
+    `git checkout -b \<name of your branch\> test`
+
+   * To push modifs :  
+    from project root folder ("twelve-heroes/") :
+       1) `git add .` ( <-- with '.', it will add all modified files for a commit)
+       2) `git commit -m "description of the change"`
+       3) `git push origin \<name of your branch\>`
+  
+### 4. To run the app for tests
+   * go in project root folder ("twelve-heroes/")
+   * do **once** : `npm install` (<-- this will install all dependencies, might take some time)
+   * do : `npm run start`  
+    Wait.... It will run the server (socket.io stuff) and launch app in chrome  
+    ( or do : `npm run dev` to launch app in chrome only without server)
+
+
+
+## **Some info about the project**
+
+### 1. npm stuff
+   * file *package.json* contains project config for npm
+   * File *package-lock.json* is generated by npm. It never needs to be changed manually
+   * Directory *node_modules* contains all dependant libraries. It is not on git, it is only locally
+   * npm is usefull to keep track of dependencies and install them rapidly.
+   * it provides npm scripts (see [**below**](#npm-scripts)). These are shortcuts for bilding, testing, deploying
+
+### 2. Editor config & VS code settings
+   * File *.editorconfig* contains config for editing
+   * Install on VS code the plugin "EditorConfig for Visual Studio Code"
+   * It will ensure we have same code format
+   * With VS code, select code and select "Format Selection"
+   * File *settings.json* contains config for VS code editor (overrides global config)
+
+### 3. ES lint
+   * File *.eslintrc.json* contains Linter configuration
+   * It defines common coding rules
+   * It acts like a "compiler", it will throw warnings or errors if coding rules were not respected
+
+### 4. Babel
+   * File *.babelrc* contains Babel config
+   * Here we can use Javascript ES6 to code (new keywords like 'class')
+   * Babel takes care of "transpiling" this ES6 code to ES5
+   * Most browsers are compatible ES5 and not ES6, this is why it is necessary
+
+### 5. Cordova
+   * File *config.xml* contains Cordova config
+   * Cordova is a framework that will package our app for Apple or Android
+   * Directory "*plugins*" and "*platforms*" are not in git. They are used by Cordova when used to run the project.
+
+### 6. Webpack
+   * File *webpack.config.js* contains webpack config
+   * Webpack is a powerful tool that lightens the code and bundles it intelligently. It is kind of a "compiler"
+   * It also allows to run a local server to test our JS code (using BrowserSync plugin)
+   * It supports "Hot reloading", meaning that once app is running, you can modify the code and it will reloads live in the browser
+   * Directory "*www*" is where webpack is going to put the "compiled" app
+
+### 7. Git ignore
+   * File *.gitignore* is used for git
+   * It defines the files we don't want to version on git (like build files, binaries, external node libraries) 
+
+### 8. Source code
+   * "*src*" contains app code (client code)
+   * "*server*" contains server code
+
+
+
+## **NPM scripts**
+"scripts": {
+
+    "server": "babel-node server/main.js",
+    "dev": "webpack --watch",
+    "precor-build": "cordova prepare",
+    "cor-build": "CORDOVA=true cordova build -- --webpackConfig webpack.config.js",
+    "cordova": "CORDOVA=true cordova run -- -w webpack.config.js",
+    "start": "npm-run-all --parallel server dev lint:watch",
+    "lint": "esw webpack.config.* src --color",
+    "lint:watch": "npm run lint -- --watch",
+    "localtunnel": "lt --port 3000",
+    "share": "npm-run-all --parallel open:src localtunnel",
+    "test": "mocha --reporter progress \"src/**/*.test.js\"",
+    "test:watch": "npm run test -- --watch",
+    "clean": "git clean -fdx -e node_modules"
+  }
+
+### 1. How NPM scripts work
+   * In *package.json*, in section *"scripts"* are defined the npm scripts
+   * `npm run <script name>` will run *\<script name\>*
+   * `npm start` is a shortcut for `npm run start`
+   * *pre* and *post* keywords :
+     * Using **pre**script-name and **post**script-name
+     * with `npm run script-name` it will first run **pre**script-name, then script-name, and finally **post**script-name
+   * Using **npm-run-all**, it will run at the same time all the scripts declared behind this keyword
+     * Useful for example to run clients and server at the same time, along with the "linting"
+
+### 2. Description of the project npm scripts
+   * `npm run server`
+     * It launches the server (listening for clients connections using sockets)
+   * `npm run dev`
+     * It is launching the app for dev (not using cordova)
+   * `npm cor-build`
+     * It builds the code and prepares it for Cordova
+   * `npm run cordova`
+     * It runs the app using Cordova
+     * Today the only target is "browser" (no Apple or Android yet)
+   * **`npm run start` or `npm start`**
+     * It runs in parallel the server, the app and the linting
+     * While it is running you can modify app code and save
+       * The linter will show live new errors or warnings, if any
+       * Refresh page on chrome to see the changes
+   * `npm run lint`
+     * It checks the code once, see [above]((#3-es-lint))
+   * `npm run lint:watch`
+     * It checks the code, see [above]((#3-es-lint))
+     * In addition to the command above, it checks live again the code after save
+   * `npm run localtunnel`
+     * It allows to share temporarily the app
+     * After running `npm start` or `npm run dev`
+     * Run this and it will give a public http address
+     * If other person goes to this http address it will access the app
+     * Useful to share briefly to the other what we are doing
+     * **Use *run share* below instead**
+   * `npm run share`
+     * It runs in parallel the dev and localtunnel
+   * `npm run test`
+     * It runs *once* all the tests : all files *.test.js
+     * Says what passed or failed
+   * `npm run test:watch`
+     * It runs the tests like above, after modifs to code and save, it will re-run automatically the tests
+   * `npm run clean`
+     * It cleans the build directory
+     * **WARNING : It will also remove new files or directory created and not added yet into git**
+
+## **Useful links**
+
+### 1. Google drive stuff
+https://drive.google.com/open?id=11j-IW2OL5ZOaeF3YGyvXjFDLz7BJdpW_
+
+### 2. Trello
+https://trello.com/b/FZXHfg2J/twelve-heroes