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.0 KiB

Raw Blame History

Contribution guidelines

Development environment

Prerequisites

PHP 8.1+
make
entr to watch for file changes
xdg-open link handler to invoke browser
libgd (php-gd, phpX.Y-gd) for downsizing images

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.

Running your own copy

point your webserver at the output folder
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 seperator: Hyphen (-)

PHP

Identifier casing: snake_case and CONSTANT_CASE

Comments and documentation: PHPDoc

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.0 KiB Raw Blame History