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.
64 lines
2.1 KiB
Markdown
64 lines
2.1 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
|
|
|
|
### 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 hooks 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 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](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/)
|