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.
107 lines
3.9 KiB
Markdown
107 lines
3.9 KiB
Markdown
# Contribution guidelines
|
|
|
|
## Development environment
|
|
|
|
### Prerequisites
|
|
|
|
- PHP 8.1+
|
|
- `make`, `awk`, `xargs`
|
|
- `entr` to watch for file changes
|
|
- `xdg-open` link handler to invoke browser
|
|
- `libgd` (`php-gd`, `phpX.Y-gd`) for downsizing images
|
|
- `zstd` to archive files (when using `--archive` flag)
|
|
- (Optional) `doxygen` to generate documentation
|
|
|
|
### 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 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`](Makefile) for more details.
|
|
|
|
Recommended:
|
|
|
|
- Add the [default include paths](.phpenv) (`.`, `php`) to your PHP intellisense.
|
|
|
|
- Get [EditorConfig](https://editorconfig.org/#pre-installed) for your IDE if not pre-installed.
|
|
|
|
- Symlink the commit hooks provided in [`etc/hooks`](etc/hooks/) to `.git/hooks/<hook>` to run a full test cycle when committing to main.
|
|
|
|
- Use `doxygen` (or `make docs`) to generate documentation you can reference when developing.
|
|
|
|
#### Note on include paths
|
|
|
|
The current working directory of all entrypoints in the `sites` directory is anchored to `sites` itself.
|
|
This ensures that references to components are not broken when the page changes locations. For example, `require '+getenv.php';` works in both `index.php` and `about/index.php`. However, as a result, files included from such endpoints (even from the `php/` subtree) may have their parent folders shadowed when trying to use `include` themselves. Files in the same folder and in subfolders can be included, however. How PHP's `include` fallback mechanism implies this behavior is unclear.
|
|
|
|
### Running your own copy
|
|
|
|
- point your webserver at the [`output`](output/) folder
|
|
- edit [`sites/privacy.php`](sites/privacy.php) to correspond to your Privacy Policy
|
|
- 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 separator**: Hyphen (`-`)
|
|
|
|
### PHP
|
|
|
|
**Identifier casing**: `snake_case` and `CONSTANT_CASE`
|
|
|
|
**Comments and documentation**: [Doxygen](https://en.wikipedia.org/wiki/Doxygen)
|
|
|
|
**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:
|
|
|
|
```php
|
|
<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](https://jsdoc.app/)
|