Skip to content

Latest commit

 

History

History
259 lines (171 loc) · 9.58 KB

decisions.adoc

File metadata and controls

259 lines (171 loc) · 9.58 KB
Raw

Talkyard Decisions

In this file: Decisions made when building Talkyard, about how to do things, and how Not do things.

Usage:

1) Before adding any 3rd party lib, e.g. react-transition-group, search this file for the name of that lib, and related words, e.g. "animations". Because maybe a decision was made to Not use that lib and do things in other ways instead. And it’d be annoying if these decisions got forgotten so that years later, things got done in the bad ways.

2) Before making any non-trivial decision, search this file for related words, and see if there’re related thoughts and previous decisions here, already.

Long ago

Use Webdriver.io for end-to-end tests because:

  • It supports Multiremote, i.e. running many browsers at the same time in the same test, useful for testing e.g. the chat system.

  • It has synchronous commands: console.log(browser.getTitle()) instead of browser.getTitle().then(title ⇒ console.log(title)) (or async await everywhere?).

  • It is under active development (even more nowadays 2020-11).

Year 2020

Use Asciidoc for documentation

2020-05-16: Use Asciidoc for docs, not Markdown or CommonMark.

Why? See e.g.: https://news.ycombinator.com/item?id=18848278: "I’ve entirely replaced markdown and been using asciidoctor for both documentation and general writing. Asciidoctor is far superior to Markdown [ …​]". You can also websearch: "site:news.ycombinator.com markdown vs asciidoc".

As of 2020-05 most Ty docs are in Markdown. But don’t add any more Markdown docs. And some day, can run sth like: find . -type f -name '*.md' -exec pandoc -f markdown -t asciidoc {} \; to convert from .md to .adoc. https://news.ycombinator.com/item?id=22875242

Use CSS animations

2020-05-16: Don’t add react-transition-group or any other animations lib. [REACTANIMS] Only use CSS anims in Ty for now.

CSS animations are simple and fast and keep the bundles small. Others agree: "use it instead of importing javascript libraries, your bundle remains small. And browser spends fewer resources" https://medium.com/@dmitrynozhenko/5-ways-to-animate-a-reactjs-app-in-2019-56eb9af6e3bf

"ReactTransitionGroup has small size" they write, but: react-transition-group.min.js is 5,6K min.js.gz (v4.4.1, May 2020) — that’s too much for Talkyard! (at least for now, for slim-bundle).

Don’t use Nodejs server side

Don’t use Express (expressjs.com) or sth like that. Hard to reason about security, e.g.: https://hackerone.com/reports/712065, who could have guessed:

const _ = require('lodash');
.zipObjectDeep(['proto_.z'],[123])
_.zipObjectDeep(['a.b.__proto__.c'],[456])
console.log(z) // 123
console.log(c) // 456

Plus other vulns all the time in js libs it seems to me. And 9999 microdependencies —> supply chain attacks made simple. "npm has more than 1.2M of public packages […​] perfect target for cybercriminals" writes https://snyk.io/blog/what-is-a-backdoor. Look: is-odd and is-even: https://news.ycombinator.com/item?id=16901188.

Using Javascript in the browser, though, is different — as long as the browser talks only with the Ty server.

Also better not use Python or Ruby for server code.

SECURITY [to_ty_risky] to-talkyard is a bit risky: nodejs code that parses user defined data. Use a different lang? Run in sandbox?

Edit, half a year (?) later: Turns out there’s a "Nodejs done right", namely Deno, by he who created Nodejs actually. Ty might use Deno for scripting (instead of js or bash).

Vendor everything

Vendor all dependencies, i.e. bundle their source code (or at least JARs) together with Talkyard.

Four reasons:

  • Security. Can diff changes in vendored deps.

  • Developer friendliness. Seems some people are behind company firewalls and proxy servers that break downloading some dependencies. But accessing Git seems to have worked for everyone.

  • Continuous Integration. Then good if can build offline?

  • Reproducible builds (also requires using a specific OS? Which should be mostly fine, since things get built in Docker containers with a specific OS and version — but will need to specify the exact image hash?) [repr_builds]

  • Working offline. If the wifi stops working and your phone too (no tethering).

Place the vendored stuff in Git submodules. Then, if the vendored stuff’s Git repos eventually grows large because of old historical commit objects, those Git submodules can be squashed or sth like that, making them small again — without affecting the history in the main repo (it’d just be updated to point to the squashed stuff).

"Join" or "Sign Up" button title

What should the join community button title be? [join_or_signup]

"Join", "Sign Up", "Create Account", "Register"? _ - Not "Register" — sounds like the tax agency. - Not "Create Account" — that’s too long, causes UX trickiness on 400 px wide phones. - Not "Sign up" because non-native English speakers sometimes don’t know the difference between "Sign Up" and "Sign In", or "Sign Up" and "Log In". (See e.g.: https://ell.stackexchange.com/questions/24384/what-is-the-difference-among-sign-up-sign-in-and-log-in )

But "Join" is simple to understand? And short and friendly? So "Join" it’ll be.

Don’t use "Sign in" for the login button title either, because can get confused with "Sign up", and also, is 1 letter longer than "Log in". Facebook uses "Log in" so "everyone" should be used to this.

So: "Join" and "Log in" and "Log out", in Talkyard.

Sort posts by time, by default [why_sort_by_time]

Talkyard used to (before 2020-11-25) sort replies by most-popular-first. However I think this was confusing, in that most of the time, people don’t upvote others' replies — so most of the time, replies are in effect sorted by time only, …​

  1. Except for sometimes, someone clicks Like, causing the thereafter upvoted post, to berak the seemingly by-time sort order. Making things look a bit random?

Instead, there can be a one-click button "Show Popular Replies" or "Show best answers", to sort best-first.

There’s a per site config value to change the sort order — maybe per category or topic one day? Topic type? Q&A = best-first, others by time?

Don’t use shared CDN

It’s pointless: Chrome >= v86 partitions the cache by URL, and Safari too, so there’re no performance benefits — instead, slightly slower, because of a TLS handshake. The previous browser behaviour enabled cross-site tracking, checking if the user had visited certain sites etc.

Git submodules, not subtrees

Talkyard already uses somewhat many submodules — and then, if starting to use subtrees too, "everyone" would have to learn two different things: both submodules and subtrees.

Year 2021

Use lua-resty-acme for automatic HTTPS

There’s also lua-resty-auto-ssl but it has a dependency on Dehydrated, a Bash script — whilst lua-resty-acme is Lua only: simpler to install and to understand the code. It’s actively developed by Kong which Ty a bit depends on indirectly anyway because they sometimes contribute to OpenResty. See: fffonion/lua-resty-acme#5

Use Snowpack; skip Webpack and Parcel

Procrastinating isn’t too bad — now, thanks to having done nothing for years (just Typescript and concatenated files with Gulpjs), suddenly Snowpack has appeared, and looks better than Webpack, Parcel and Browserify. (Rollup? Snowpack uses Rollup.)

It’s ok to continue using ElasticSearch

Elastic recently (2021-01) announced they’ll change from Apache2 to Server Side Public License (SSPL):

However they dual-license under both SSPL and the Elastic License — the latter allows using ElasticSearch the way Talkyard does it: all Basic features are available at no cost, when using ES via object code (not source code) and when the primary purpose is not ElasticSearch itself. In Ty’s case, the primary purpose with Ty is not ES, but discussions between humans. From the license:

You agree not to: …​ (iv) use Elastic Software Object Code for providing …​ software-as-a-service, …​ where obtaining access to the Elastic Software or the features and functions of the Elastic Software is a primary reason or substantial motivation for users of the SaaS Offering to access and/or use the SaaS Offering …​

Also, it seems only Elastic may distribute the ES object code:

You agree not to: (iii) …​ distribute, sublicense, …​ Elastic Software Object Code,

That’s fine — with Talkyard, people download the ElasticSearch Docker image themselves (via Docker-Compose) from Elastic’s own servers — see images/search/Dockerfile.

(FYI: Talkyards' source code integrating with ElasticSearch (via its REST API) is about 750 lines? See app/talkyard/server/search/. Whilst Ty’s whole code base is about 160 000 lines? (as of 2021-01), I don’t remember exactly — anyway, the directly related to ElasticSearch code in Talkyard should be < 0.5%? of everything. This can make it easy to understand, also for outsiders, that the primary benefit with Talkyard really is not ElasticSearch. Also, that should be about how much code would need to change, if replacing ElasticSearch with, say PostgreSQL’s search or some of the upcoming alternatives in Rust or Golang.)