# Contribution guidelines ## Development environment ### Prerequisites - PHP 8.1+ - `make`, `awk`, `xargs` - `entr` to watch for file changes - `xdg-open` link handler to invoke browser - `libgd` (`php-gd`, `phpX.Y-gd`) for downsizing images - `zstd` to archive files (when using `--archive` flag) - (Optional) `doxygen` to generate documentation ### Official repositories - Codeberg: - Lokinet Gitea (mirror): - GitHub (archive): - Lokinet Gitea (archive): ### Structure [`fetch-servers.php`](php/fetch-servers.php) queries available servers, and [`generate-html.php`](php/generate-html.php>) generates static HTML. Static HTML is generated from the [`sites`](sites) directory to the [`output`](output) directory, which additionally contains static assets. All contents of `sites` are invoked to produce a HTML page unless they are prefixed with a `+` sign. ### Development Run at least once: `make fetch` to query servers. This takes around 15 seconds thanks to the coroutine implementation. Run when developing: `make dev` to watch for changes & serve HTML locally in browser. See [`Makefile`](Makefile) for more details. Recommended: - Add the [default include paths](.phpenv) (`.`, `php`) to your PHP intellisense. - Get [EditorConfig](https://editorconfig.org/#pre-installed) for your IDE if not pre-installed. - Symlink the commit hooks provided in [`etc/hooks`](etc/hooks/) to `.git/hooks/` to run a full test cycle when committing to main. - Use `doxygen` (or `make docs`) to generate documentation you can reference when developing. #### Note on include paths The current working directory of all entrypoints in the `sites` directory is anchored to `sites` itself. This ensures that references to components are not broken when the page changes locations. For example, `require '+getenv.php';` works in both `index.php` and `about/index.php`. However, as a result, files included from such endpoints (even from the `php/` subtree) may have their parent folders shadowed when trying to use `include` themselves. Files in the same folder and in subfolders can be included, however. How PHP's `include` fallback mechanism implies this behavior is unclear. ### Running your own copy - point your webserver at the [`output`](output/) folder - edit [`sites/privacy.php`](sites/privacy.php) to correspond to your Privacy Policy - install and enable systemd services from the [`etc/systemd`](etc/systemd/) folder or an equivalent timer for periodic updates ## Code style guidelines ### General **Indentation**: Tabs (4-wide) **Filename separator**: Hyphen (`-`) ### PHP **Identifier casing**: `snake_case` and `CONSTANT_CASE` **Comments and documentation**: [Doxygen](https://en.wikipedia.org/wiki/Doxygen) **Whitespace**: - The following exceptions apply to PHP expressions embedded within HTML: - Flow control statements within HTML (``) shall have zero indentation, akin to C macros or sh heredocs. - Self-contained PHP `include` and variable shorthand statements in multi-line HTML child node position shall be followed by an extra line: ```php

has_food()): ?> describe_food() ?>

``` **Other**: - Strings shall be surrounded by single quotes `''` where no variable expansion is taking place ### HTML & CSS **Identifier casing**: `kebab-case`, legacy `snake_case` **Comments and documentation**: PHP no-ops instead of HTML comments, if possible ### JavaScript **Identifier casing**: `camelCase` and `CONSTANT_CASE`, occasional `snake_case` for references to DOM **Comments and documentation**: [JSDoc](https://jsdoc.app/)