add README.md

1 files changed, 59 insertions, 0 deletions

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..54a5d21
--- /dev/null
+++ b/README.md
@@ -0,0 +1,59 @@
+# Vote
+
+A MediaWiki extension to provide a user-friendly graphical
+user interface for votes conducted on wiki pages.  To add
+a vote to a page you just add the `<vote>` tag as follows:
+
+    <vote>
+    </vote>
+
+This extension then turns this tag into a web form with radio buttons
+for the available options (approve, oppose and abstain) and a textarea
+to attach a comment to the vote. When you submit the form, the extension
+simply edits the page, inserting a new line before the closing `</vote>`
+tag. By storing the votes in the page text all the changes are
+conveniently and transparently tracked in the page history.
+
+Additional features include:
+
+* The votes are automatically tallied.
+
+* You can change your vote by just submitting the form again
+  (your last vote counts).
+
+* An end date may be specified for the vote with the `end` attribute
+  e.g. with `<vote end=2022-10-15>` the vote will close on the 15th
+  October 2022 at 23:59 in the [wiki timezone].
+  After the deadline the web form to add new votes disappears.
+
+* A vote may be cancelled by adding the `cancel` attribute,
+  e.g. `<vote cancel>`.
+
+* Any line within the `<vote>` tag that does not start with `* `
+  is skipped when tallying, so it is possible to reply to votes
+  by editing the wikitext, e.g:
+
+      <vote>
+      * 2022-10-14 12:28 Alice: NO I am concerned that ...
+      : Some reply to Alice ... --~~~~
+      * 2022-10-14 12:30 Bob: YES I think that ...
+      </vote>
+
+Pages with open votes are by default tracked in the
+`Category:Pages with open votes` category (which can be customized
+by editing `MediaWiki:pages-with-open-votes-category`).
+
+[wiki timezone]: https://www.mediawiki.org/wiki/Manual:Timezone
+
+## Backstory
+
+The extension was developed by [push-f] for the [OpenStreetMap Wiki] to
+make its [proposal voting process] more welcoming to people unfamiliar
+with wikitext. OpenStreetMap is edited by hundreds of thousands people,
+most of which are probably unfamiliar with wiki editing. While in
+comparison only very few people participate in the proposal voting,
+everybody is welcome to do so, so it makes sense to simplify the process.
+
+[push-f]: https://push-f.com/
+[OpenStreetMap Wiki]: https://wiki.openstreetmap.org/
+[proposal voting process]: https://wiki.openstreetmap.org/wiki/Proposal_process#Voting