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

Raw Permalink Blame History

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: https://codeberg.org/gravel/sessioncommunities.online
Lokinet Gitea (mirror): https://lokilocker.com/gravel/sessioncommunities.online
GitHub (archive): https://github.com/mdPlusPlus/sessioncommunities.online
Lokinet Gitea (archive): https://lokilocker.com/SomeGuy/sessioncommunities.online

Structure

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.

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

Recommended:

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

General

Indentation: Tabs (4-wide)

Filename separator: Hyphen (-)

PHP

Identifier casing: snake_case and CONSTANT_CASE

Comments and documentation: Doxygen

Whitespace:

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:

<body>
    <div>
<?php if ($bowl->has_food()): ?>
        <?= $bowl->describe_food() ?>

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

<?php endif; ?>
    </div>
</body>

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

3.9 KiB Raw Permalink Blame History