From 4c094024e1edfa49344547e26097d4b6ff2c103c Mon Sep 17 00:00:00 2001 From: gravel Date: Sat, 4 Mar 2023 14:18:00 +0000 Subject: [PATCH] Add CONTRIBUTING.md --- CONTRIBUTING.md | 65 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 65 insertions(+) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..1cb5dc1 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,65 @@ +# Contribution guidelines + +## Development environment + +### Prerequisites + +- PHP (version TBD) +- `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 ` +- `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**: TBD + +### HTML & CSS + +**Identifier casing**: `kebab-case`, occasional `snake_case` + +**Comments and documentation**: TBD + +### JavaScript + +**Identifier casing**: `camelCase` and `CONSTANT_CASE`, occasional `snake_case` + +**Comments and documentation**: [JSDoc](https://jsdoc.app/) + +## Contact + +- Web Development Session Community on [caliban.org](https://sog.caliban.org/) +- Project lead, querying logic, deployment, community filtering: `someguy` on Session +- Documentation, code quality, HTML generation, CSS, JS: `gravel` on Session