You cannot select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

3.9 KiB

Contribution guidelines

Development environment


  • 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


fetch-servers.php queries available servers, and generate-html.php generates static HTML. Static HTML is generated from the sites directory to the 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.


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 for more details.


  • Add the default include paths (., php) to your PHP intellisense.

  • Get EditorConfig for your IDE if not pre-installed.

  • Symlink the commit hooks provided in etc/hooks to .git/hooks/<hook> 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 folder
  • edit sites/privacy.php to correspond to your Privacy Policy
  • install and enable systemd services from the etc/systemd folder or an equivalent timer for periodic updates

Code style guidelines


Indentation: Tabs (4-wide)

Filename separator: Hyphen (-)


Identifier casing: snake_case and CONSTANT_CASE

Comments and documentation: Doxygen


  • The following exceptions apply to PHP expressions embedded within HTML:
    • Flow control statements within HTML (<?php if ($condition): >) 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 if ($bowl->has_food()): ?>
        <?= $bowl->describe_food() ?>

<?php else: ?>
        <?php include 'bowl-empty.php'; ?>

<?php endif; ?>


  • Strings shall be surrounded by single quotes '' where no variable expansion is taking place


Identifier casing: kebab-case, legacy snake_case

Comments and documentation: PHP no-ops instead of HTML comments, if possible


Identifier casing: camelCase and CONSTANT_CASE, occasional snake_case for references to DOM

Comments and documentation: JSDoc