|
|
|
|
# Contribution guidelines
|
|
|
|
|
|
|
|
|
|
## Development environment
|
|
|
|
|
|
|
|
|
|
### Prerequisites
|
|
|
|
|
|
|
|
|
|
- PHP 8.1+
|
|
|
|
|
- `make`
|
|
|
|
|
- `entr` to watch for file changes
|
|
|
|
|
- `xdg-open` link handler to invoke browser
|
|
|
|
|
- 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`
|
|
|
|
|
|
|
|
|
|
### 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.
|
|
|
|
|
Does not respond to new files.
|
|
|
|
|
|
|
|
|
|
See [`Makefile`](Makefile) for more details.
|
|
|
|
|
|
|
|
|
|
### Running your own copy
|
|
|
|
|
|
|
|
|
|
- point your webserver at the `output` folder
|
|
|
|
|
- install systemd services from the `systemd` folder or an equivalent timer
|
|
|
|
|
- `session_sudoers`: TBD
|
|
|
|
|
|
|
|
|
|
## 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/)
|
|
|
|
|
|
|
|
|
|
## Contact
|
|
|
|
|
|
|
|
|
|
- Web Development Session Community on [caliban.org](https://sog.caliban.org/)
|
|
|
|
|
- Project lead, deployment, community filtering: `someguy` on Session
|
|
|
|
|
- Documentation, code quality, querying logic, HTML generation, CSS, JS: `gravel` on Session
|
