--- /dev/null
+You are welcome to contribute to Trivabble to the code, the documentation, graphics, design, or any other aspect.
+The more we are working on the project, the funnier.
+However, the current maintainer is grumpy and opinionated.
+
+# Discuss with us, and then work
+
+As a consequence, you are highly encouraged to open an issue in the bug tracker to tell us what you want to work on so:
+
+- we can avoid duplicate effort and discovering at the last moment two people were working on the same feature at the same time;
+- we can tell you if we agree with this addition / modification. We would hate to have to reject your work after the facts.
+ This is really important: when a feature is added, it is forever. We often can't remove a feature without being hated by our users.
+ See the really good talk of Lichess's original author.
+ We also want to keep the UI uncluttered and dead simple to figure out.
+ Trivabble is used by people who are not into computers *at all*.
+- we can discuss the implementation together to increase the chances your code will be merged.
+
+Trivabble is currently hosted at gitlab.com. You are not forced to register on Gitlab.com or use to contribute to Trivabble.
+Git works well by mail, so you are free to find the maintainer's email and discuss with them and send a patch or a link to a git branch hosted somewhere here.
+However, if you do so, everybody might be missing out on collective thinking.
+
+## Recommended flow
+
+1. Open a ticket.
+2. We discuss.
+3. You work on whatever you want to work.
+4. If you work on the code or the documentation, open a merge request whenever you want. Clearly tell us whether your branch is ready for review, or not so nobody wastes their time reviewing something that will change a lot. But we are keen to give early / continuous feedback if you'd like to have some ☺. We can also share a branch if needed.
+
+## Risky flow
+
+Contributing should be fun.
+You can still work on your own, fiddle with the code and open a merge request or send patches when you think we should have a look.
+But be aware that we could refuse to merge your work if we think the stars aren't aligned or for any other dumb or reasonable reason.
+
+# Code Management and Coding style
+
+## Linting
+
+Please lint your code. Run `make eslint` before committing.
+We use a custom set of rules.
+The specific coding style does not really matter but we need uniformity.
+Four spaces, mandatory semicolon, spaces after statement keywords, spaces around infix operators, and you should be good for the most part.
+ESLint will warn you if you do something a bit off.
+This frees us from speaking about coding styles when merging code, while still guaranteeing some uniformity.
+
+## No advanced JavaScript features for the client side
+
+The code needs to work on Safari 9.
+Use `let` and `const` to declare variables. They are replaced by `var` with `sed` to make it work on this ancient browser.
+It's hacky, we are parsing Javascript like Chtulus, but it works well in practice.
+It's tested during development because the development server also rewrites Javascript using the same regular expression, so it cannot go really wrong.
+Any error will be spotted before going to production.
+
+Other than that, do not use other recent feature of Javascript.
+We don't use any transpiler and do not intend to do so in the foreseeable future.
+We will drop support for the iPad 2 at some point but for now, this means:
+
+ - no arrow functions
+ - no default or rest parameters
+ - no deconstruction
+ - no ellipsis in objects litterals
+ - be careful: you will need to turn DOM lists (like those returned by `querySelectorAll` and `getElements*` function) into regular arrays using `Array.from`.
+ This one is tricky since you don't need to do this in current versions of the browser.
+
+Check compatibility with caniuse or MDN if unsure.
+
+The maintainer will take care of testing your code for this, but if you wish to test the compatibility of your code and don't have a device running Safari 9 (or because a Mac is required to debug Javascript running on the iPad and you don't have one… *sigh*), you can spin up a Debian Jessie container / virtual machine and install Uzbl or Surf, which are based on a very similar version of WebKit.
+
+On the server side, you can go wild. But we currently support Node 10, which is still maintained, so you'll need a very good reason to break compatibility with node 10.
+
+## No external dependencies
+
+Trivabble is very lightweight, server side as well as client side, and quite is simple to deploy.
+We'd like to keep it this way.
+Dependencies are a burden to maintain, especially in the JavaScript world where one module will come with hundreds of recursive dependencies. Hikes.
+See how we went out of our way to implement WebSocket ourselves in the server code so we didn't have to add a dependency.
+However, if you have a very good reason to add an external dependency, we are ready to reconsider, especially if the feature requiring the external dependencies is optional.
# Trivabble
-Trivabble is a network Scrabble® game.
+Trivabble is free a network Scrabble game under the (AGPLv3 license)[LICENSE].
+It is not in any way connected to Hasbro, who has the rights on the trademark Scrabble.
+Trivabble provides a board, a bag full of tiles, racks and a chat.
+People can play without registering and join each other by using the same game number.
-This Readme is yet to be written, however, everything is documented in French at [https://trivabble.1s.fr/](https://trivabble.1s.fr/). English is coming soon!
+It features:
+ - a board, a bag full of tiles, a rack for every player
+ - a chat so people can communicate
+ - a way to set the score of each player
+ - support for different languages (set of tiles as well as the interface)
+Trivabble does not implement any rule: you are free to play your way.
+It does not understand what you do and is not able to compute the score, like your real board game.
+
+Trivabble needs to be installed on a server, and is playable from a browser.
+
+It supports:
+ - latest versions of Firefox and Chromium
+ - Mobile browsers on Android
+ - Safari 9 and later on the iPad
+
+It should work on any browser released after 2015, though we haven't tested it on Internet Explorer.
+
+This documentation is intented for people who want to install Trivabble on their server.
+If you just want to play, head to https://trivabble.1s.fr/.
+
+For contributions, see (contributing)[CONTRIBUTING.md].
+
+## Set up for production
+
+Note: Please be aware that this is alpha-quality software.
+We do our best to avoid breaking stuff but we might from time to time.
+With this out of the way…
+
+Trivabble is composed of two parts: the server and the client.
+
+- The server is a Javascript program that runs on Node JS.
+ It waits for HTTP and WebSocket requests on a configurable port (default: 3000), and a configurable address (default: localhost).
+ This server needs to run for Trivabble to work, and proxified through a Web server like Apache or Nginx.
+- The client is a set of static files that need to be server by a Web server
+
+### Prerequisite
+
+You need to have:
+ - Node (version 10 or later)
+ - make
+ - git
+ - a Web server such as Apache or Nginx.
+
+On a Debian-based system, the following command will install make and node:
+
+ apt install make nodejs git
+
+On some systems, the node binary does not exist and is called `nodejs` instead. Trivabble expects the Node binary to be `node`. On these systems, a `nodejs-legacy` package may exist to fix this. Otherwise, you will need to create a symblink.
+
+As for the web server, we will asume that you already have one running and correctly configured.
+
+### Installation
+
+We will assume www-data is the UNIX user of your Web server. Adapt if necessary.
+
+1. Set up the directories that will host the server and the client.
+ Create a UNIX user for the Trivabble server and set the right permission:
+ The server should be outside the root of your Web server.
+ The client will be served by your Web server.
+
+ Let's store the chosen paths in environment variables (adapt if necessary) and create these directories:
+
+ ```sh
+ export TRIVABBLE_SERVER_PATH=/opt/trivabble-server
+ export TRIVABBLE_PUBLIC_PATH=/var/www/html/trivabble
+
+ sudo useradd trivabble
+ sudo mkdir -p "$TRIVABBLE_PUBLIC_PATH"
+ sudo chown trivabble:www-data "$TRIVABBLE_PUBLIC_PATH"
+ sudo chmod g+x "$TRIVABBLE_PUBLIC_PATH"
+ sudo mkdir -p "$TRIVABBLE_SERVER_PATH"
+ sudo chown trivabble "$TRIVABBLE_PUBLIC_PATH"
+ ```
+
+2. Clone the repository somewhere (in your HOME directory for instance):
+
+ ```sh
+ git clone https://gitlab.com/raphj/trivabble.git
+ cd trivabble
+ ```
+
+3. Get the latest production version:
+
+ ```sh
+ git checkout "$(git tag --list '[prod]*' --sort=v:refname | tail -1)"
+ ```
+
+4. Make sure you still have your environment variable set (adapt if necessary):
+
+ ```sh
+ export TRIVABBLE_SERVER_PATH=/opt/trivabble-server
+ export TRIVABBLE_PUBLIC_PATH=/var/www/html/trivabble
+ ```
+
+ Also make sure you still are in the trivabble repository.
+
+5. Run:
+
+ ```sh
+ sudo -H -u www-data ./bin/upgrade-prod.sh --prod-public-dir "$TRIVABBLE_PUBLIC_PATH" --prod-server-dir "$TRIVABBLE_SERVER_PATH"
+ ```
+
+ This will:
+ - run `make` so everything that needs to be build will be built, including the language files
+ - transform Javascript files so they are compatible with older browsers
+ - copy the server and client files to the chosen folders
+
+6. (Optional) - In the public directory (`$TRIVABBLE_PUBLIC_PATH`), review `config.js.sample`. If there are values you would like to change, copy it to config.js and make the desired changes.
+
+7. Run the Trivabble server.
+
+ ```sh
+ cd "$TRIVABBLE_SERVER_PATH"
+ node trivabble-server
+ ```
+
+ You may want to run this in a `screen` so you can leave the session and trivabble-server still runs in the background.
+
+ Better yet, create a service for your init system:
+
+ - create `/usr/local/bin/start-trivabble`:
+
+ ```
+ #!/bin/sh
+ cd /var/www/html/raph/raw/trivabble
+ exec sudo -u www-data DEBUG_LOG=true nodejs trivabble-server.js
+ ```
+
+8. Configure your web server.
+
+On Apache 2, the relevant rules are:
+
+ RewriteEngine on
+ RewriteRule "^/?:trivabble/ws/(.*)" ws://localhost:3000/ws/$1 [P]
+
+ ProxyPass "/:trivabble" http://localhost:3000/ retry=0
+ ProxyPassReverse "/:trivabble" http://localhost:3000/
+
+You will need to enable modules `proxy_http`, `proxy_wstunnel` (if you do not disable websockets in `config.js`) and `rewrite`:
+
+```sh
+a2enmod proxy_http
+a2enmod proxy_wstunnel
+a2enmod rewrite
+```
+
+A full example is available in (doc/trivabble-apache-host.conf.sample)[doc/trivabble-apache-host.conf.sample].
+
+:warning: Be careful to allow enough concurrent processes / threads / workers on your web server.
+Each player requires one long-standing connection (XHR, SSE or WebSocket), plus small requests when not using WebSockets.
Soft'N'Design Software / projects / trivabble.git / commitdiff
