write readme, add license

2 files changed, 58 insertions, 1 deletions

diff --git a/license.txt b/license.txt
new file mode 100644
index 0000000..9699d94
--- /dev/null
+++ b/license.txt
@@ -0,0 +1,13 @@
+Copyright 2024 Benji Dial
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED “AS IS” AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
+OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.
diff --git a/readme.txt b/readme.txt
index fdb5cc1..c6c1e59 100644
--- a/readme.txt
+++ b/readme.txt
@@ -1 +1,45 @@
-to do: write readme.
+=== bracket bot ===
+
+before you begin, you will need the following:
+* a discord bot token
+    (see e.g. https://github.com/reactiflux/discord-irc/wiki/Creating-a-discord-bot-&-getting-a-token)
+* the channel id of the channel where the polls should be posted
+    (see https://support.discord.com/hc/en-us/articles/206346498-Where-can-I-find-my-User-Server-Message-ID)
+* a list of entries for your bracket
+
+to build the bracket bot, just run make. the bracket bot uses libcurl,
+libsqlite3, and Niels Lohmann's json library. the json library is downloaded
+at build time. the required packages to build on debian are the following:
+* g++
+* libcurl-dev (this is a virtual package, satisfiable by a few options)
+* libsqlite3-dev
+* make
+* wget
+
+when the bot is run, it expects the following environment variables:
+* BOT_TOKEN: the bot token
+* CHANNEL_ID: the channel id
+* POLLS_PER_DAY: the number of polls to post each day
+* POST_TIME_UTC: the number of seconds past midnight utc to post the polls
+    (for example, to post at midnight eastern daylight time, set this to 14400)
+and it expects to find a list of entries, separated by newlines, in a file
+named entries.txt in the directory where it is run.
+
+the bot creates a sqlite3 database in database.db, with the following tables:
+* misc: this contains one column and one row with the current round number
+* entries: a list of every entry
+  * name: the name of the entry
+  * round: if the entry has been eliminated, a zero. if the entry has passed
+    the current round, then the number of the next round. if the entry has not
+    appeared in a poll this round, or is in an active poll, then the number of
+    the current round.
+  * in_active_poll: if the entry is in an active poll, a one, otherwise a zero
+* active_polls: a list of the message ids for the active polls
+* past_polls: a list of every concluded poll
+  * round: the round where this poll happened
+  * entry_1: the name of the first entry
+  * entry_2: the name of the second entry
+  * users_1: the user ids of the users who voted
+    for the first entry, separated by commas
+  * users_2: the user ids of the users who voted
+    for the second entry, separated by commas