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.
70 lines
2.2 KiB
Markdown
70 lines
2.2 KiB
Markdown
# 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.
|
|
|
|
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 [`systemd`](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/)
|