From 1332f9f38a2a5f92af1a418cc0f15f11e7cc5390 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Rapha=C3=ABl=20Jakse?= Date: Sat, 16 May 2020 15:26:25 +0200 Subject: [PATCH] Documentation: README and CONTRIBUTING --- CONTRIBUTING.md | 76 +++++++++++++++++++++++ README.md | 156 +++++++++++++++++++++++++++++++++++++++++++++++- 2 files changed, 230 insertions(+), 2 deletions(-) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..bfecad4 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,76 @@ +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. diff --git a/README.md b/README.md index 68b4c09..d7218c4 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,158 @@ # 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.