trivabble/CONTRIBUTING.md

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.