Documentation

BUILD.md

+# Requirements
+
+THe project is built and deployed on Debian 12.
+Any similar setup should work though.
+
+# Build
+
+```bash
+apt install clang clang-format libfcgi-dev make minify
+make
+```
+
+Optionally, local deploy for testing:
+
+```bash
+apt install lighttpd
+lighty-enable-mod fastcgi
+make install
+```
+
+# Deploy
+
+TODO: done with CI/CD
+
+```bash
+apt install lighttpd libfcgi-bin
+lighty-enable-mod fastcgi
+```
+
+TODO: how to acquire pre-compiled binaries & pre-minified assets
+
+```bash
+mkdir --parents /var/www/cgi-bin
+cp yomomma.fcgi /var/www/cgi-bin/
+minify -r -o /var/www/cgi-bin/ assets
+cp assets/jokes.txt /var/www/cgi-bin/assets/
+cp conf-available/99-yomomma.conf /etc/lighttpd/conf-available/
+lighty-enable-mod yomomma
+service lighttpd force-reload
+```

CONTRIBUTING.md

+# Rules
+
+1. No JavaScript!
+1. No cookies
+1. No tracking
+
+The website should be as simple & fast as possible.
+It shouldn't care what browser/client is being used, if the client is a person, a bot, an assistive tool, etc.
+
+The one exception is if we choose to enable particularly old clients (e.g. retrocomputing).
+If and only where necessary, we can use the user agent string to server compatible versions to old clients.
+
+# Standards
+
+## C
+
+We are using ANSI X3.159-1989 a.k.a. C89, because it is funny to use an extremely old C spec to serve up modern HTML & CSS.
+
+## HTML
+
+The output webpage must be compliant with the HTML5 spec.
+The one possible exception is links may use direct UTF-8 since all modern browsers support them.
+
+(Possible exception since by my read, the spec is ambiguous on if raw UTF-8 is allowed or not.)
+
+## CSS
+
+All CSS used must be compliant with the CSS 3 spec.
+
+# Code Style
+
+The goal of this project is to produce the smallest, fastest website possible.
+However, we only care about the speed and bandwidth of the compiled/deployed site.
+
+Changes that produce faster-running binaries or reduce bandwidth are encouraged.
+But changes that only make the source code smaller (code-golf) are discouraged.
+
+## C
+
+C code should follow the [WebKit Code Style Guidelines][].
+Code can be automatically formatted with clang-tidy (`make pretty`).
+Code style is verified by a CI/CD job on commit.
+
+## HTML
+
+HTML source should be formatted for readability over conciseness.
+Minification is largely a solved problem, so we simply minify the files as part of the build.
+
+However, ideas to get smaller final HTML are welcome!
+
+[WebKit Code Style Guidelines]: https://www.webkit.org/coding/coding-style.html

README.md

 Belligerently light/tight (unlike yo momma) website to serve yo momma jokes.
 
-# Build
-
-Assuming Debian 12 or similar.
-
-```bash
-apt install clang clang-format libfcgi-dev make minify
-make
-```
-
-Optionally, local deploy for testing:
-
-```bash
-apt install lighttpd
-lighty-enable-mod fastcgi
-make install
-```
-
-# Deploy
-
-```bash
-apt install lighttpd libfcgi-bin
-lighty-enable-mod fastcgi
-```
-
-TODO: how to acquire pre-compiled binaries & pre-minified assets
-
-```bash
-mkdir --parents /var/www/cgi-bin
-cp yomomma.fcgi /var/www/cgi-bin/
-minify -r -o /var/www/cgi-bin/ assets
-cp assets/jokes.txt /var/www/cgi-bin/assets/
-cp conf-available/99-yomomma.conf /etc/lighttpd/conf-available/
-lighty-enable-mod yomomma
-service lighttpd force-reload
-```
-
-# TODO
-
-- Pipeline
-  - Format code
-  - Build and produce a .tar for download (amd64 only initially)
-    - Making a 32-bit version to deploy to my livingroom-p3 would also be hilarious
-  - Deploy on tag!
-- Code format
-  - Code format our HTML source too!
-- Commit a list of royalty-free jokes
-- favicon
-- Set caching policy
-  - Long cache on favicon, CSS, and static HTML (≥ 1 day, ≤ 1 year)
-  - No cache (0 seconds) on main page to get new jokes every time
-- Production deploy tuning
-  - https://blog.fosketts.net/2009/06/29/tuning-lighttpd-linux
-  - Need to increase max files to allow more than 307 parallel connections.
-    We are targeting 2000, so we need fd ≥ 7500.
-  - Might lower keep-alive values too
-    - server.max-keep-alive-idle to ~3 seconds (though default is 5 and probably fine)
-    - server.max-read-idle to ~10 seconds (this page will be TINY)
-    - server.max-write-idle to ~10 seconds (we don't allow uploads anyway)
+To follow along at home, see [BUILD.md](BUILD.md).
+See [CONTRIBUTING.md](CONTRIBUTING.md) for rules / style.