Merge pull request 'Update README.md, add CONTRIBUTING.md' (#25) from gravel/sessioncommunities.online:docs into main

Reviewed-on: #25

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 <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**: 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

README.md

@@ -22,39 +22,34 @@ https://getsession.org/
 
 Currently this script crawls the following sites:
 
-- https://github.com/GNU-Linux-libre/Awesome-Session-Group-List
-- https://lokilocker.com/Mods/Session-Groups/wiki/Session-Open-Groups
-- https://session.directory/
+- <https://github.com/GNU-Linux-libre/Awesome-Session-Group-List>
+- <https://lokilocker.com/Mods/Session-Groups/wiki/Session-Open-Groups>
+- <https://session.directory/>
 
-Additionally, the following open community servers are polled:
+Additionally, a few other servers are hardcoded, see [querying logic](php/fetch-servers.php).
 
-- https://open.getsession.org
-- http://13.233.251.36:8081
+### How does this work?
 
-### Steps
+The [`update-listing.php`](php/update-listing.php) script invokes the following two PHP scripts: [`fetch-servers.php`](php/fetch-servers.php) to query available servers, and [`generate-html.php`](php/generate-html.php>) to generate the static HTML.
+
+The querying logic consists of these steps:
 
 1. Fetching source HTML: `get_html_from_known_sources()`
 1. Extracting Session invites from the HTML:
 `extract_join_links_from_html()` and `get_servers_from_join_links()`
 1. Making sure servers are online: `reduce_servers()`
 1. Querying the servers for all available rooms
-and normalize active user numbers: `query_servers_for_rooms()`
+and normalizing active user numbers: `query_servers_for_rooms()`
 1. De-duplicating servers based on public keys:
 `get_pubkeys_of_servers()` and `reduce_addresses_of_pubkeys()`
 1. Aggregating all server info & adding language data: `generate_info_arrays()`
-1. Generating static HTML content: `generateHTML()`
-
-### Legacy support
 
-Right now we fully support legacy SOGS servers, 
-although this support is likely going to be dropped soon, 
-since those servers can not even be joined anymore with current Session clients.  
-Dropping legacy support will also increase maintainability.
+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.
 
 ### Work around bad routing to Chinese servers
 
 Depending on your location, it is possible for you to get really bad routing to
-SOGS servers behind the GFW. In this case, 
+SOGS servers behind the [GFW](https://en.wikipedia.org/wiki/Great_Firewall). In this case,
 the initial connection is still successful, but you'll never receive
 any actual content and the retrieval attempt will simply time out.
 This happens randomly. To make sure this won't affect the results, we simply
@@ -64,16 +59,17 @@ until we eventually get the content.
 The details can be seen in `curl_get_contents()`.
 
 ### Official repositories
-- https://github.com/mdPlusPlus/sessioncommunities.online
-- https://lokilocker.com/SomeGuy/sessioncommunities.online
+
+- GitHub: <https://github.com/mdPlusPlus/sessioncommunities.online>
+- Lokinet Gitea: <https://lokilocker.com/SomeGuy/sessioncommunities.online>
 
 If your favourite Session community is missing a language flag,
 you can issue a pull request here:
-- https://github.com/mdPlusPlus/sessioncommunities.online-languages/
 
+- <https://github.com/mdPlusPlus/sessioncommunities.online-languages/>
 
 ## Contact
 
 If you want to contact me, you can add me on Session via my
 [ONS](https://docs.oxen.io/using-the-oxen-blockchain/using-oxen-name-system):
-"someguy" (without the quotes)
+`someguy`.