From 9a5f7df7a40a1376b547b6a144ef82b979943c60 Mon Sep 17 00:00:00 2001
From: Sebastian Crane <seabass-labrax@gmx.com>
Date: Sun, 27 Feb 2022 21:56:10 +0000
Subject: [PATCH] Add README.md

Signed-off-by: Sebastian Crane <seabass-labrax@gmx.com>
---
 README.md | 90 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 90 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..4ddee61
--- /dev/null
+++ b/README.md
@@ -0,0 +1,90 @@
+<!--- SPDX-License-Identifier: Apache-2.0 -->
+<!--- SPDX-FileCopyrightText: 2022 Sebastian Crane <seabass-labrax@gmx.com> -->
+
+# matchbot
+
+A chatbot for announcing upcoming matches and finding fellow players, written for the [LibreGaming](https://libregaming.org) community
+
+## Running
+
+1. Install Clojure - you can use [Clojure's official installation guide](https://clojure.org/guides/getting_started) or your distribution's package.
+
+2. Clone this repository:
+
+``` bash
+git clone https://git.libregaming.org/LibreGaming/matchbot.git
+cd matchbot
+```
+
+3. Create a configuration file, `config.yaml`, in YAML format:
+
+``` yaml
+data-file: "matchbot-data.json"
+irc:
+  server: example.com
+  port: 6667
+  nick: matchbot
+  channel: "##matchbot-test"
+```
+
+4. Run `matchbot`:
+
+``` bash
+clojure -M -m system
+```
+
+## Usage
+
+**`!list`** - show all the games that have a list of players
+
+**`!match game`** - announce a match of `game` to all of its players
+
+**`!players game`** - show all the players of `game`
+
+**`!add game`** - add yourself to the list of players for `game`
+
+**`!remove game`** - remove yourself from the list of players for `game`
+
+**`!help`** - show available commands with their explanations
+
+## Development
+
+### Running the tests
+
+`matchbot` includes automated unit tests for many functions, along with a simple test runner configuration with [Kaocha](https://cljdoc.org/d/lambdaisland/kaocha/).
+Running the tests is a similar process to running the main application:
+
+```bash
+clojure -M:test -m kaocha.runner
+```
+
+### Starting a development REPL
+
+When developing `matchbot`, it can be more convenient and efficient to work interactively with a REPL integrated into your text editor.
+Since `matchbot` uses Clojure's [tools.deps library](https://clojure.org/guides/deps_and_cli), the best way to start is by following [the relevant part of the nREPL documentation](https://nrepl.org/nrepl/usage/server.html#using-clojure-cli-tools) to create a user-level `deps.edn` file, then install the [nREPL extension for your text editor](https://nrepl.org/nrepl/usage/clients.html#editorsides).
+
+You can create, start and stop an instance of the chatbot process with the functions in the `system` namespace:
+
+``` clojure
+;; creating a new instance
+(def my-instance (atom (system/system)))
+
+;; starting the instance
+(swap! my-instance system/start)
+
+;; restarting the instance
+(system/restart my-instance)
+
+;; stopping and resetting the instance
+(swap! my-instance stop)
+(reset! my-instance (system/system))
+```
+
+Once you are familiar with nREPL, you can additionally use [tools.namespace.repl](https://github.com/clojure/tools.namespace) to make reevaluating (reloading) your changes easier:
+
+``` clojure
+(require '[clojure.tools.namespace.repl :refer [refresh]])
+(refresh)
+```
+
+Make sure that you create your system instance in the REPL, since `refresh` will forcefully delete the instance if it has been defined in another namespace!