diff --git a/README.md b/README.md
index 5d67c04d..3e68bd8b 100644
--- a/README.md
+++ b/README.md
@@ -4,6 +4,9 @@
XMPP Extension Protocols (XEPs)
===============================
+About
+-----
+
This repository is used to manage work on XMPP Extension Protocols
(XEPs), which are the specifications produced by the XMPP Standards
Foundation (XSF). See http://xmpp.org/ for details. The rendered
@@ -11,6 +14,9 @@ documents can be found here:
https://xmpp.org/extensions/
+Contribution
+------------
+
Please use this repository to raise issues and submit pull requests:
https://github.com/xsf/xeps/issues
@@ -19,7 +25,7 @@ https://github.com/xsf/xeps/pulls
For in-depth technical discussion, please post to the standards@xmpp.org
email list:
-http://mail.jabber.org/mailman/listinfo/standards
+https://mail.jabber.org/mailman/listinfo/standards
To submit a new proposal for consideration as a XEP, please read this
page:
@@ -29,387 +35,11 @@ https://xmpp.org/about/standards-process.html#submitting-a-xep
[XEP-0001: XMPP Extension Protocols](https://xmpp.org/extensions/xep-0001.html)
defines the standards process followed by the XMPP Standards Foundation.
-Building XEPs
--------------
-
-You'll need xmllint and xsltproc.
-
-On Ubuntu, you can install them with `sudo apt install libxml2-utils xsltproc`
-
-To build a single XEP as HTML simply run:
-
- make xep-xxxx.html
-
-To build PDFs, you'll need to install [TeXML](http://getfo.org/texml/) (probably
-in a Python 2 virtual environment).
-You can then build PDFs with:
-
- make xep-xxxx.pdf
-
-To change the output directory, set the variable `OUTDIR`, eg.
-
- OUTDIR=/tmp/xeps make all
-
-For more information try `make help`.
-
-Using Docker
-------------
-
-A full set of HTML and PDFs can be generated inside a docker container, with no
-dependencies on the host other than Docker itself, and served by nginx in the
-container. To build the template `make docker`, to run it `make testdocker`
-(serves on http://localhost:3080), and to stop/delete it afterwards `make
-stopdocker`
-
-
-Gardening (Issue triaging by non-editors)
------------------------------------------
-
-For new PRs, anyone with permission may perform gardening tasks.
-The [Go wiki] summarizes "gardening" as:
-
-> the background maintenance tasks done to keep the project healthy & growing &
-> nice looking.
-
-In this repo, gardening is mostly triaging issues.
-An issue is considered triaged when an editor has been assigned to it.
-Untriaged issues that are in need of attention can be found using the following
-filter: [`is:open is:pr no:assignee`]
-
-To triage new issues or PRs, see the [Triaging a PR][#triaging-a-pr] section below.
-
Editor
-======
+------
-The XMPP Extensions Editor (or, for short, XEP Editor) manages the XMPP
-extensions process as defined in XMPP Extension Protocols ([XEP-0001]).
-In addition, the XEP Editor functions as the XMPP Registrar as defined in XMPP
-Registrar Function ([XEP-0053]).
-Read those documents first, since this README focuses on mechanics instead of
-philosophy or policy.
+Documentation for Editors is in the [docs](docs/) folder.
-All PRs
--------
-
-For all PRs, start by ensuring that the IP release has been signed and that CI
-has run and no issues were detected before merging.
-
-
-Triaging a PR
--------------
-
-If the PR is not touching a XEP, this guide does not apply. If the PR touches
-multiple XEPs, go through the steps for each XEP and exit at the first which
-applies.
-
-1. Is the PR a ProtoXEP?
-
- 1. Does the PR touch existing XEPs? Close as [invalid] and ask the Opener
- to split the two things.
-
- 2. Add the [ProtoXEP] and [Ready to Merge] labels.
- 3. Stop.
-
-2. Sanity checks
-
- 1. Ensure that all XEPs are mentioned in the title as `XEP-XXXX`. E.g. `XEP-0084, XEP-0123: something`.
- 2. Continue.
-
-3. Are the changes *for all XEPs* purely editorial?
-
- 1. Add the [Editorial Change] and [Ready to Merge] labels.
- 2. If the PR does not add a revision block, add the [Needs Version Block] label.
- 3. If the PR adds a revision block and does not only bump the patch-level (third) version number part, add the [Needs Version Block] label and a comment explaining the situation.
- 4. Stop.
-
-4. Is the XEP **not** in Experimental state?
-
- (Changes to Non—Experimental XEPs need approval by the approving body as
- defined in the XEP file itself.)
-
- 1. Add the [Needs Council]/[Needs Board] label.
- 2. Send an email to the council chair and/or announce the PR in [The Council Room].
- 3. If the PR does not add a revision block, add the [Needs Version Block] label.
- 4. If the PR adds a revision block and does not bump the minor-level (second) version number part, add the [Needs Version Block] label and a comment explaining the situation.
- 5. Stop.
-
-5. Is the XEP in Experimental state and the PR opener is not an author of the
- XEP?
-
- 1. If the PR does not a revision block, add the [Needs Version Block] label.
- 2. If the PR adds a revision block and does not bump the minor-level (second) version number part, add the [Needs Version Block] label and a comment explaining the situation.
- 3. If the issue has not been discussed on the standards list *or* if
- the authors have not been involved in the discussion *or* the author
- has not explicitly ACKed the PR:
-
- 1. Make sure the standards@ discussion (if it exists) is linked in the
- PR.
- 2. Add the [Needs Author] label.
- 3. Stop.
-
-6. Mark the PR as [Ready to Merge].
-
-Discussions
------------
-
-Technical discussions SHOULD NOT happen in the xeps repository. If you see a
-discussion evolve into technical (as opposed to editorial) matters, do the
-following (I haven’t tried that myself yet, so feel especially free to improve
-the process):
-
-1. Lock the conversation.
-2. Copy the technical discussion parts into an email to standards@. My
- preferred format for this would be something along the lines of:
-
- Subject: XEP-1234: [insert PR subject here, or something more appropriate]
-
- There was some discussion on the xeps repository an XEP-1234, which got
- technical. I moved this discussion to standards@ so that the whole
- community is aware of the issue and can participate.
-
- @user1 wrote:
- > quote user1 here ...
-
- @user2 wrote:
- > quote user2 here ...
-
- Remove clearly editorial discussion and mark the removal with ``[…]``.
-
-3. Add the [Needs List Discussion] label to the PR and link the standards@
- thread you just created. Remove other labels (such as [Needs Author]).
-
-4. Monitor the thread; when the discussion is resolved, the PR opener will
- usually prepare an update. Unlock the conversation to allow editorial
- discussion to continue, if needed. Remove the [Needs List Discussion] label
- and re-triage the PR as described above.
-
- **Note:** The locking is mostly used here as a tool to avoid a race
- condition, not to exclude people from participating. (It would be
- unfortunate if you had to add more comments to your already-sent email.)
- Feel free to unlock at some point during the list discussion when you’re
- sure that all participants have taken note of the move.
-
-
-General notes on making changes
--------------------------------
-
-This section has some hints on the python scripts which help you doing the
-more tedious tasks of sending emails and properly archiving XEPs.
-
-*Before* you start working on merging a Pull Request:
-
-* Ideally, you have the [xep-attic] repository cloned next to the xeps
- repository.
-
-* Before starting to prepare a merge and push, ensure that you have the XEP
- metadata up-to-date locally:
-
- $ make build/xeplist.xml
-
-* Make a copy of the metadata:
-
- $ cp build/xeplist.xml tools/old-xeplist.xml
-
- (avoid putting random XML files in the xeps root directory, the build
- tooling might mistake them as XEPs; so we put it somewhere else.)
-
-*While* you’re working on a Pull Request:
-
-* Use the lokal docker build to ensure that everything is syntactically
- correct. The process is described above in "Using Docker".
-
-When you have *merged* the Pull Request and the change went through to the
-webserver (see also the [Docker Build] to track the build progress):
-
-* Send out the emails. First ensure that the new metadata is up-to-date:
-
- $ make build/xeplist.xml
-
- Check that the emails which will be sent are correct (the ``--dry-run``
- switch prevents the tool from actually sending emails):
-
- $ ./tools/send-updates.py --dry-run tools/old-xeplist.xml build/xeplist.xml standards@xmpp.org
-
- (See also the ``--help`` output for more information.)
-
- Once you’ve verified that the correct emails will be sent, actually send
- them using (note the missing ``--dry-run`` flag):
-
- $ ./tools/send-updates.py tools/old-xeplist.xml build/xeplist.xml standards@xmpp.org
-
- A few tips:
-
- 1. You can also test-send them to your own address by replacing
- ``standards@xmpp.org`` with your own address.
- 2. To avoid having to enter your email account details every time, use a
- configuration file. Invoke the tool with ``--help`` for more
- information and ask [jonasw]/[@horazont] if things are still unclear.
-
- If the tool misbehaves, pester [jonasw]/[@horazont] about it.
-
-* Don’t forget to archive the new versions of the XEPs. If you have the
- [xep-attic] cloned next to the xeps repository, you can simply run:
-
- $ ./tools/archive.py tools/old-xeplist.xml build/xeplist.xml
-
- Otherwise, you will have to explicitly give the path to the attic:
-
- $ ./tools/archive.py --attic /path/to/xep-attic/content/ tools/old-xeplist.xml build/xeplist.xml
-
- (note that the path must point to the ``content`` subdirectory of the
- [xep-attic].)
-
- Don’t forget to commit & push the changes to [xep-attic].
-
-
-New ProtoXEPs
--------------
-
-- Make sure the protoxep is in the `inbox/` tree and has a name that does not
- start with "xep-" (you may change this or ask the author to change it).
-- Make sure the version is `0.0.1` and the status is `ProtoXEP` (you may fix
- this or ask the author to fix it).
-- You may want to build the protoxep locally and ensure the HTML and PDF look
- okay.
-- Merge the PR as described in "Merging a PR". Once the email has been sent,
- continue here.
-- Create a card for the protoxep on the [Council Trello] under "Proposed
- Agendums".
-- Attach the PR to the card and link the generated HTML.
-- Comment on the PR with a link to the card, thanking the author for their
- submission and letting them know that their XEP will be voted on within the
- next two weeks.
-- If the council forgets and doesn't vote on the protoxep, pester them until
- they do.
-- If the council rejects the XEP, you're done (leave the XEP in the inbox and
- inform the author of the councils decision). Otherwise, see
- "Promoting a ProtoXEP".
-
-
-Promoting a ProtoXEP
---------------------
-
-- It is easiest to start a new branch, in case you screw something up on the way.
-- Once the council approves a ProtoXEP, *copy* it out of the inbox and into the
- root, assigning it the next available number in the XEP series.
-- Modify the `` element in the XML file to match.
-- Set the version to `0.1` and the initials to `XEP Editor: xyz` (replacing "xyz" with your own initials).
-- Remove the `` element from the XML file if it is included.
-- Set the status to `Experimental`.
-- Add a reference to the XEP in `xep.ent`.
-- Make a commit.
-- Treat your branch as you would treat a [Ready to Merge] PR in "Merging a PR".
- (you don’t need to create another branch though.)
-
-
-Promoting XEPs
---------------
-
-Ensure that the following sections exist (if not, ask the author to add them
-before promoting the XEP):
-
-- Security Considerations
-- IANA Considerations
-- XMPP Registrar Considerations
-- XML Schema (for protocol specifications)
-
-You can also refer to `xep-template.xml` for a recommended list of sections and
-whether or not they are required.
-For a helpful graph of how XEP promotion works, see [XEP-0001].
-
-
-Deferring XEPs
---------------
-
-Before Deferring XEPs, read the "General notes on making changes" section.
-
-XEPs get deferred after 12 months of inactivity. There is a tool which handles
-that process automatically, if it is invoked regularly.
-
-First of all, you need an up-to-date ``xeplist.xml``:
-
- make build/xeplist.xml
-
-To get a list of XEPs which need to be deferred (without changing anything),
-run:
-
- ./tools/deferrals.py -v
-
-To apply the deferrals, make a new feature branch and execute:
-
- ./tools/deferrals.py -m 'initials'
-
-where you replace ``initials`` with your editor initials so that it is obvious
-who made the change (those initials will be used in the revision block).
-
-This will modify the XEPs in-place. It uses heuristics for incrementing the
-version number, finding and inserting the revision block as well as changing
-the status. Yes, it involves regular expressions (because we don’t want to
-fully re-write the XML to keep the diffs minimal). It is thus vital that you
-**use `git diff` to ensure that the changes are sane**. If the changes
-are sane, make a commit and merge to master as described in "Merging a PR",
-in accordance with the "General notes on making changes".
-
-
-Merging a PR
-------------
-
-Before Merging a PR, read the "General notes on making changes" section.
-
-When you get to the point that the PR is [Ready to Merge], do the following:
-
-1. Create a new branch off master called ``feature/xep-1234`` (if the PR
- touches multiple XEPs, I call it ``feature/xep-0678,xep-0789``).
-
-2. Merge all [Ready to Merge] PRs which affect the XEP(s) into that branch.
-
-3. Resolve conflicts.
-
-4. If the PRs introduced multiple revision blocks, squash it down to a single
- revision block. Set "XEP Editor (initials)" as author of the revision block
- and add the initials of the original PR authors to the changelog entries.
- (If that doesn’t make sense to you, you’ll find plenty examples in the
- XEPs.)
-
-5. Ensure that everything builds by performing a full docker build (see above).
-
- (Once the docker build reaches the point where the XEPs are built, you can
- switch branches and work on another PR.)
-
-6. If the build passes, check that the generated files look sane by running the
- docker container.
-
-7. Merge the PR into master. If you are working on independent changes to
- multiple XEPs, you can merge them all in one go.
-
-8. If you merged multiple things into master, re-do the docker build check.
-
-9. Push.
-
-10. Go back to "General notes on making changes".
-
-
-
-[XEP-0001]: https://xmpp.org/extensions/xep-0001.html
-[XEP-0053]: https://xmpp.org/extensions/xep-0053.html
-[Editor Trello]: https://trello.com/b/gwcOFnCr
-[Council Trello]: https://trello.com/b/ww7zWMlI
-[Needs Council]: https://github.com/xsf/xeps/labels/Needs%20Council
-[Needs Board]: https://github.com/xsf/xeps/labels/Needs%20Board
-[ProtoXEP]: https://github.com/xsf/xeps/labels/ProtoXEP
-[Go wiki]: https://golang.org/wiki/Gardening
-[`is:open is:pr no:assignee`]: https://github.com/xsf/xeps/pulls?utf8=%E2%9C%93&q=is%3Aopen%20is%3Apr%20no%3Aassignee%20
-[Needs Author]: https://github.com/xsf/xeps/labels/Needs%20Author
-[Ready to Merge]: https://github.com/xsf/xeps/labels/Ready%20to%20Merge
-[Needs List Discussion]: https://github.com/xsf/xeps/labels/Needs%20List%20Discussion
-[Needs Version Block]: https://github.com/xsf/xeps/labels/Needs%20Version%20Block
-[Editorial Change]: https://github.com/xsf/xeps/labels/Editorial%20Change
-[xep-attic]: https://github.com/xsf/xep-attic
-[Docker Build]: https://hub.docker.com/r/xmppxsf/xeps/builds/
-[@horazont]: https://github.com/horazont/
-[jonasw]: https://wiki.xmpp.org/web/User:Jwi
-[The Council Room]: xmpp:council@muc.xmpp.org?join
-
[modeline]: # ( vim: set fenc=utf-8 ff=unix spell spl=en textwidth=80: )
diff --git a/docs/MODERATION.md b/docs/MODERATION.md
new file mode 100644
index 00000000..dc8a421d
--- /dev/null
+++ b/docs/MODERATION.md
@@ -0,0 +1,39 @@
+# Moderation
+
+## Discussions
+
+Technical discussions SHOULD NOT happen in the xeps repository. If you see a
+discussion evolve into technical (as opposed to editorial) matters, do the
+following:
+
+1. Lock the conversation.
+2. Copy the technical discussion parts into an email to standards@. My
+ preferred format for this would be something along the lines of:
+
+ Subject: [insert PR title here, or something more appropriate]
+
+ There was some discussion on the xeps repository an XEP-1234, which got
+ technical. I moved this discussion to standards@ so that the whole
+ community is aware of the issue and can participate.
+
+ @user1 wrote:
+ > quote user1 here ...
+
+ @user2 wrote:
+ > quote user2 here ...
+
+ Remove clearly editorial discussion and mark the removal with ``[…]``.
+
+3. Add the [Needs List Discussion] label to the PR and link the standards@
+ thread you just created. Remove other labels (such as [Needs Author]).
+
+4. Monitor the thread; when the discussion is resolved, the PR opener will
+ usually prepare an update. Unlock the conversation to allow editorial
+ discussion to continue, if needed. Remove the [Needs List Discussion] label
+ and re-triage the PR as described above.
+
+ **Note:** The locking is mostly used here as a tool to avoid a race
+ condition, not to exclude people from participating. (It would be
+ unfortunate if you had to add more comments to your already-sent email.)
+ Feel free to unlock at some point during the list discussion when you’re
+ sure that all participants have taken note of the move.
diff --git a/docs/PROCESSING.md b/docs/PROCESSING.md
new file mode 100644
index 00000000..10b52448
--- /dev/null
+++ b/docs/PROCESSING.md
@@ -0,0 +1,203 @@
+# Processing a PR
+
+## General notes on making changes
+
+This section has some hints on the python scripts which help you doing the
+more tedious tasks of sending emails and properly archiving XEPs.
+
+### Before you start working on merging a Pull Request
+
+* Ideally, you have the [xep-attic] repository cloned next to the xeps
+ repository.
+
+* Before starting to prepare a merge and push, ensure that you have the XEP
+ metadata up-to-date locally:
+
+ $ make build/xeplist.xml
+
+* Make a copy of the metadata:
+
+ $ cp build/xeplist.xml tools/old-xeplist.xml
+
+ (avoid putting random XML files in the xeps root directory, the build
+ tooling might mistake them as XEPs; so we put it somewhere else.)
+
+### While you’re working on a Pull Request
+
+* Use the local docker build to ensure that everything is syntactically
+ correct. The process is described above in "Using Docker".
+
+### After merging the Pull Request
+
+When you have *merged* the Pull Request and the change went through to the
+webserver (see also the [Docker Build] to track the build progress):
+
+* Send out the emails. First ensure that the new metadata is up-to-date:
+
+ $ make build/xeplist.xml
+
+ Check that the emails which will be sent are correct (the ``--dry-run``
+ switch prevents the tool from actually sending emails):
+
+ $ ./tools/send-updates.py --dry-run tools/old-xeplist.xml build/xeplist.xml standards@xmpp.org
+
+ (See also the ``--help`` output for more information.)
+
+ Once you’ve verified that the correct emails will be sent, actually send
+ them using (note the missing ``--dry-run`` flag):
+
+ $ ./tools/send-updates.py tools/old-xeplist.xml build/xeplist.xml standards@xmpp.org
+
+ A few tips:
+
+ 1. You can also test-send them to your own address by replacing
+ ``standards@xmpp.org`` with your own address.
+ 2. To avoid having to enter your email account details every time, use a
+ configuration file. Invoke the tool with ``--help`` for more
+ information and ask [jonas’]/[@horazont] if things are still unclear.
+
+ If the tool misbehaves, pester [jonas’]/[@horazont] about it.
+
+* Don’t forget to archive the new versions of the XEPs. If you have the
+ [xep-attic] cloned next to the xeps repository, you can simply run:
+
+ $ ./tools/archive.py tools/old-xeplist.xml build/xeplist.xml
+
+ Otherwise, you will have to explicitly give the path to the attic:
+
+ $ ./tools/archive.py --attic /path/to/xep-attic/content/ tools/old-xeplist.xml build/xeplist.xml
+
+ (note that the path must point to the ``content`` subdirectory of the
+ [xep-attic].)
+
+ Don’t forget to commit & push the changes to [xep-attic].
+
+
+## New ProtoXEPs
+
+- Make sure the protoxep is in the `inbox/` tree and has a name that does not
+ start with "xep-" (you may change this or ask the author to change it).
+- Make sure the version is `0.0.1` and the status is `ProtoXEP` (you may fix
+ this or ask the author to fix it).
+- You may want to build the protoxep locally and ensure the HTML and PDF look
+ okay.
+- Merge the PR as described in "Merging a PR". Once the email has been sent,
+ continue here.
+- Create a card for the protoxep on the [Council Trello] under "Proposed
+ Agendums".
+- Attach the PR to the card and link the generated HTML.
+- Comment on the PR with a link to the card, thanking the author for their
+ submission and letting them know that their XEP will be voted on within the
+ next two weeks.
+- If the council forgets and doesn't vote on the protoxep, pester them until
+ they do.
+- If the council rejects the XEP, you're done (leave the XEP in the inbox and
+ inform the author of the councils decision). Otherwise, see
+ "Promoting a ProtoXEP".
+
+
+## Promoting a ProtoXEP to Experimental
+
+- It is easiest to start a new branch, in case you screw something up on the way.
+- Once the council approves a ProtoXEP, *copy* it out of the inbox and into the
+ root, assigning it the next available number in the XEP series.
+- Modify the `` element in the XML file to match.
+- Set the version to `0.1` and the initials to `XEP Editor: xyz` (replacing "xyz" with your own initials).
+- Remove the `` element from the XML file if it is included.
+- Set the status to `Experimental`.
+- Add a reference to the XEP in `xep.ent`.
+- Make a commit.
+- Treat your branch as you would treat a [Ready to Merge] PR in "Merging a PR".
+ (you don’t need to create another branch though.)
+
+
+## Promoting XEPs beyond Experimental
+
+Ensure that the following sections exist (if not, ask the author to add them
+before promoting the XEP):
+
+- Security Considerations
+- IANA Considerations
+- XMPP Registrar Considerations
+- XML Schema (for protocol specifications)
+
+You can also refer to `xep-template.xml` for a recommended list of sections and
+whether or not they are required.
+For a helpful graph of how XEP promotion works, see [XEP-0001].
+
+
+## Deferring XEPs
+
+Before Deferring XEPs, read the "General notes on making changes" section.
+
+XEPs get deferred after 12 months of inactivity. There is a tool which handles
+that process automatically, if it is invoked regularly.
+
+First of all, you need an up-to-date ``xeplist.xml``:
+
+ make build/xeplist.xml
+
+To get a list of XEPs which need to be deferred (without changing anything),
+run:
+
+ ./tools/deferrals.py -v
+
+To apply the deferrals, make a new feature branch and execute:
+
+ ./tools/deferrals.py -m 'initials'
+
+where you replace ``initials`` with your editor initials so that it is obvious
+who made the change (those initials will be used in the revision block).
+
+This will modify the XEPs in-place. It uses heuristics for incrementing the
+version number, finding and inserting the revision block as well as changing
+the status. Yes, it involves regular expressions (because we don’t want to
+fully re-write the XML to keep the diffs minimal). It is thus vital that you
+**use `git diff` to ensure that the changes are sane**. If the changes
+are sane, make a commit and merge to master as described in "Merging a PR",
+in accordance with the "General notes on making changes".
+
+
+## Merging a PR
+
+Before Merging a PR, read the "General notes on making changes" section.
+
+When you get to the point that the PR is [Ready to Merge], do the following:
+
+1. Create a new branch off master called ``feature/xep-1234`` (if the PR
+ touches multiple XEPs, I call it ``feature/xep-0678,xep-0789``).
+
+2. Merge all [Ready to Merge] PRs which affect the XEP(s) into that branch.
+
+3. Resolve conflicts.
+
+4. If the PRs introduced multiple revision blocks, squash it down to a single
+ revision block. Set "XEP Editor (initials)" as author of the revision block
+ and add the initials of the original PR authors to the changelog entries.
+ (If that doesn’t make sense to you, you’ll find plenty examples in the
+ XEPs.)
+
+5. Ensure that everything builds by performing a full docker build (see above).
+
+ (Once the docker build reaches the point where the XEPs are built, you can
+ switch branches and work on another PR.)
+
+6. If the build passes, check that the generated files look sane by running the
+ docker container.
+
+7. Merge the PR into master. If you are working on independent changes to
+ multiple XEPs, you can merge them all in one go.
+
+8. If you merged multiple things into master, re-do the docker build check.
+
+9. Push.
+
+10. Go back to "General notes on making changes".
+
+[XEP-0001]: https://xmpp.org/extensions/xep-0001.html
+[Ready to Merge]: https://github.com/xsf/xeps/labels/Ready%20to%20Merge
+[Council Trello]: https://trello.com/b/ww7zWMlI
+[xep-attic]: https://github.com/xsf/xep-attic
+[Docker Build]: https://hub.docker.com/r/xmppxsf/xeps/builds/
+[@horazont]: https://github.com/horazont/
+[jonas’]: https://wiki.xmpp.org/web/User:Jwi
diff --git a/docs/README.md b/docs/README.md
new file mode 100644
index 00000000..b9b4a2be
--- /dev/null
+++ b/docs/README.md
@@ -0,0 +1,39 @@
+Editor Guide
+============
+
+The XMPP Extensions Editor (or, for short, XEP Editor) manages the XMPP
+extensions process as defined in XMPP Extension Protocols ([XEP-0001]).
+In addition, the XEP Editor functions as the XMPP Registrar as defined in XMPP
+Registrar Function ([XEP-0053]).
+Read those documents first, since this README focuses on mechanics instead of
+philosophy or policy.
+
+
+This is the entrypoint definitive guide for Editors.
+
+- [Using the repository](REPOSITORY.md)
+
+ Information about how to build XEPs and how the repository is laid out.
+
+
+
+- [Triaging](TRIAGING.md)
+
+ Rules for labelling and guiding inbound Pull Requests (Merge Requests).
+
+- [Processing](PROCESSING.md)
+
+ Rules and guidelines for processing inbound Pull Requests (Merge Requests)
+ towards master/main.
+
+- [Moderation](MODERATION.md)
+
+ Rules and guidelines for moderating the discussions in the PRs.
+
+
+[XEP-0053]: https://xmpp.org/extensions/xep-0053.html
diff --git a/docs/REPOSITORY.md b/docs/REPOSITORY.md
new file mode 100644
index 00000000..1bf28b8f
--- /dev/null
+++ b/docs/REPOSITORY.md
@@ -0,0 +1,34 @@
+Using the repository
+====================
+
+Building XEPs
+-------------
+
+You'll need xmllint and xsltproc.
+
+On Ubuntu, you can install them with `sudo apt install libxml2-utils xsltproc`
+
+To build a single XEP as HTML simply run:
+
+ make xep-xxxx.html
+
+To build PDFs, you'll need to install [TeXML](http://getfo.org/texml/) (probably
+in a Python 2 virtual environment).
+You can then build PDFs with:
+
+ make xep-xxxx.pdf
+
+To change the output directory, set the variable `OUTDIR`, eg.
+
+ OUTDIR=/tmp/xeps make all
+
+For more information try `make help`.
+
+Using Docker
+------------
+
+A full set of HTML and PDFs can be generated inside a docker container, with no
+dependencies on the host other than Docker itself, and served by nginx in the
+container. To build the template `make docker`, to run it `make testdocker`
+(serves on http://localhost:3080), and to stop/delete it afterwards `make
+stopdocker`
diff --git a/docs/TRIAGING.md b/docs/TRIAGING.md
new file mode 100644
index 00000000..992de116
--- /dev/null
+++ b/docs/TRIAGING.md
@@ -0,0 +1,154 @@
+# Triaging a PR
+
+## Dramatis Personae
+
+- Author: Generally the author of the PR or MR.
+- XEP Author: The Author of the XEP.
+- Approving Body: Either the XMPP Council or the XSF Board. Which of those two
+ can be determined by looking at the `` tag of the respective XEP.
+- Processing Editor: The Editor which ultimately merges a PR to master.
+
+## Labels
+
+### Approval categories
+
+- [Needs Council]: The changes need approval by the XMPP Council.
+- [Needs Board]: The changes need approval by the XSF Board.
+- [Needs Author]: The changes need approval by the XEP Author.
+- [Needs List Discussion]: The changes need more discussion on the standards@
+ (or, in rare cases, members@) mailing lists; in general, there should be a
+ link to a mailing list thread in those PRs.
+- [Editorial Change]: The changes do not need approval by anyone except the
+ Editor.
+
+### Process categories
+
+- [ProtoXEP]: The PR adds a new XEP to the inbox.
+- [Ready to Merge]: The PR can be worked on by a Processing Editor. Note that
+ this does **not** imply that no further changes are needed.
+- [Needs Version Block]: A version block needs to be added or modified before
+ the changes can enter master.
+- [Needs Editor Action]: The Processing Editor needs to do something while
+ merging the PR, aside of or in addition to modifying a version block.
+- [invalid]: The changes cannot be processed as-is at all; the PR is closed
+ without merge and without being handed to an approver.
+
+## Process
+
+### A General Note
+
+Some of the cases where the below process suggests to ask the Author to do
+something can also be handled by the Processing Editor. If it is realistic
+that the workload for the Editors would be reduced by handling the task
+themselves, use the [Needs Editor Action] label an an explanatory comment
+instead.
+
+### "Flowchart"
+
+If the PR is not touching a XEP, this guide does not apply.
+
+1. Is the PR a ProtoXEP?
+
+ 1. Does the PR touch existing XEPs? Close as [invalid] and ask the Author
+ to split the two things.
+
+ 2. Validate that the `` makes sense for the content (consult
+ [XEP-0001] if necessary). If it does not make sense, either add a
+ comment to let the Processing Editor know (adding the
+ [Needs Editor Action] label) or ask the Author to correct the problem.
+ 3. Add the [ProtoXEP] and [Ready to Merge] labels.
+ 4. Make sure the title of the PR is `XEP-XXXX: Title of the new XEP`.
+ 5. Stop.
+
+2. Sanity checks
+
+ 1. Ensure that all XEPs are mentioned in the title as `XEP-XXXX`. E.g. `XEP-0084, XEP-0123: something`.
+ 2. Continue.
+
+3. Are the changes *for all XEPs* purely editorial?
+
+ Editorial changes are changes which do not touch normative language and
+ which do not change the meaning of the text. When in doubt, treat as
+ non-Editorial.
+
+ 1. Add the [Editorial Change] and [Ready to Merge] labels.
+ 2. If the PR does not add a revision block, add the [Needs Version Block]
+ label.
+ 3. If the PR adds a revision block and does not only bump the patch-level
+ (third) version number part, add the [Needs Version Block] label and a
+ comment explaining the situation.
+ 4. Stop.
+
+4. Does the PR touch more than one XEP?
+
+ In general, we want to avoid PRs which touch multiple XEPs or which do
+ multiple non-Editorial changes at once. This is because the approving body
+ may disagree with part of the PR, which causes extra work.
+
+ Suggest the author to split the PR for that reason, unless it seems
+ realistic or obvious that the changes need to be done together to make
+ sense (an example is updating multiple XEPs which belong together, such
+ as the MIX family).
+
+4. Is the XEP **not** in Experimental state?
+
+ Changes to Non—Experimental XEPs need approval by the approving body as
+ defined in the XEP file itself.
+
+ 1. Add the [Needs Council]/[Needs Board] label. To know which, check the
+ `` of the XEPs. If the touched XEPs have different approvers
+ go back to the previous step and closely examine if the PR should not
+ be split; it is very likely that it should be split in this situation.
+ If so, tag as [invalid] and inform the author, asking them to do a
+ split.
+ 2. **For Council:** Send an email to the council chair and/or announce the
+ PR in [The Council Room].
+ **For Board:** Send an email to info@xmpp.org and/or talk directly to
+ Board members.
+ 3. If the PR does not add a revision block, add the [Needs Version Block]
+ label.
+ 4. If the PR adds a revision block and does not bump the minor-level
+ (second) version number part, add the [Needs Version Block] label and a
+ comment explaining the situation for the next Editor (the Author does
+ not need to do anything here).
+ 5. Stop.
+
+5. Is the XEP in Experimental state and the PR opener is not an author of the
+ XEP?
+
+ Changes to Experimental XEPs are approved by the XEP Authors themselves.
+ If the PR touches multiple XEPs and the XEP Authors do not overlap, ask
+ the Author to split the PR.
+
+ 1. If the PR does not a revision block, add the [Needs Version Block]
+ label.
+ 2. If the PR adds a revision block and does not bump the minor-level
+ (second) version number part, add the [Needs Version Block] label and a
+ comment explaining the situation for the Processing Editor.
+ 3. If the issue has not been discussed on the standards list *or* if
+ the XEP Author has not been involved in the discussion *or* the
+ XEP Author has not explicitly ACKed the PR:
+
+ 1. Make sure the standards@ discussion (if it exists) is linked in the
+ PR.
+ 2. Add the [Needs Author] label.
+ 3. Try to make the XEP Author aware of the change. If you do not know
+ a GitHub handle of the XEP Author, use the contact info available
+ for each author in either the XEP or in xep.ent.
+ 4. Stop.
+
+ 4. Otherwise, mark the PR as [Ready to Merge], linking the XEP Author’s
+ approval for documentation purposes.
+
+6. Mark the PR as [Ready to Merge].
+
+[ProtoXEP]: https://github.com/xsf/xeps/labels/ProtoXEP
+[Ready to Merge]: https://github.com/xsf/xeps/labels/Ready%20to%20Merge
+[Needs Author]: https://github.com/xsf/xeps/labels/Needs%20Author
+[Needs List Discussion]: https://github.com/xsf/xeps/labels/Needs%20List%20Discussion
+[Needs Version Block]: https://github.com/xsf/xeps/labels/Needs%20Version%20Block
+[Needs Editor Action]: https://github.com/xsf/xeps/labels/Needs%20Editor%20Action
+[Editorial Change]: https://github.com/xsf/xeps/labels/Editorial%20Change
+[Needs Council]: https://github.com/xsf/xeps/labels/Needs%20Council
+[Needs Board]: https://github.com/xsf/xeps/labels/Needs%20Board
+[invalid]: https://github.com/xsf/xeps/labels/invalid