# 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
- patience

### Cloning or updating the repository

Ensure the consistency of the `languages` submodule by using the following options:

- `git clone --recurse-submodules <repository-url>`
- `git pull --recurse-submodules`

### 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`](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 can take around 5 minutes.

Run when developing: `make dev` to watch for changes & serve HTML locally in browser.

Symlink the commit hook provided in [`etc/hooks`](etc/hooks/) to `.git/hooks/<hook>` to run a full test cycle when committing to main.

See [`Makefile`](Makefile) for more details.

### Running your own copy

- point your webserver at the [`output`](output/) folder
- install and enable systemd services from the [`etc/systemd`](etc/systemd/) folder or an equivalent timer

## Code style guidelines

### General

**Indentation**: Tabs (4-wide)

**Filename seperator**: Hyphen (`-`)

### PHP

**Identifier casing**: `snake_case` and `CONSTANT_CASE`

**Comments and documentation**: [PHPDoc](https://en.wikipedia.org/wiki/PHPDoc)

### 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/)