3.0 KiB
Contribution guidelines
Development environment
Prerequisites
- PHP 8.1+
make
,awk
,xargs
entr
to watch for file changesxdg-open
link handler to invoke browserlibgd
(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:
- Flow control statements within HTML (
<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