Documentation: README and CONTRIBUTING
This commit is contained in:
Raphaël Jakse
parent
e343f38e5d
commit
1332f9f38a
|
|
@ -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.
|
||||
156
README.md
156
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.
|
||||
|
|
|
|||
Loading…
Reference in New Issue