doc/README.rst: new reStructuredText README

Mainly for Codeberg, but it's nice to have something in plain text
regardless.

diff --git a/doc/README.rst b/doc/README.rst
new file mode 100644 (file)
index 0000000..b7d39c5
--- /dev/null
+++ b/doc/README.rst
@@ -0,0 +1,75 @@
+Overview
+========
+
+Managing an open source mail system with virtual users is difficult
+because every piece of software maintains its own database of users,
+domains, preferences, etc.
+
+If you're using a web interface to manage virtual users in a database,
+what happens when you delete a user? Chances are, nothing: mail
+directories are left on disk, webmail preferences are stored forever,
+address books become orphaned. A related problem is that of renaming
+an account. It's easy to move the user in one database, but then all
+of the remaining filesystem directories and databases need to be
+updated as well. (And quickly, on a running server.)
+
+Mailshears is designed to solve these problems, and currently does so
+for the following projects:
+
+* `PostfixAdmin <https://github.com/postfixadmin/postfixadmin>`_
+  (user management)
+* `Dovecot <https://dovecot.org/>`_ (physical mail storage)
+* `Roundcube <https://roundcube.net/>`_ (webmail)
+* `DAViCal <https://gitlab.com/davical-project/davical>`_
+  (calendars and contacts)
+
+
+Requirements
+============
+
+The main assumption we make is that your users are managed by
+PostfixAdmin. Plugins exist for "Dovecot" (the filesystem), DAViCal,
+and Roundcube, but they are all optional.
+
+
+How it works
+============
+
+Each plugin knows how to do perform actions:
+
+* prune
+* rename
+* remove
+
+Depending on how you invoke mailshears, it figures out which plugins
+need to be run, and then runs them in succession.
+
+By default, mailshears won't actually do anything. There's a variable
+``i_mean_business: false`` in the config file that must be set to
+``true`` before mailshears will modify the system.
+
+
+Installation
+============
+
+Use *gem* from `RubyGems <https://rubygems.org/>`_ to install the
+release tarball:
+
+.. code-block:: console
+
+  $ gem install mailshears-*.gem
+  Successfully installed mailshears-0.1.0
+  Parsing documentation for mailshears-0.1.0
+  Done installing documentation for mailshears after 0 seconds
+  1 gem installed
+
+Afterwards, create a config by copying ``mailshears.example.conf.yml``
+to ``$XDG_CONFIG_HOME/mailshears/mailshears.conf.yml``, and then edit
+it to fit your environment.
+
+
+How to report bugs
+==================
+
+Email them to me at michael@orlitzky.com, or report them on `Codeberg
+<https://codeberg.org/mjo/mailshears/issues>`_.