diff --git a/README.md b/README.md
index 2d70f5fc..e84b49cb 100644
--- a/README.md
+++ b/README.md
@@ -57,8 +57,8 @@ container. To build the template `make docker`, to run it `make testdocker`
stopdocker`
-Gardening
----------
+Gardening (Issue triaging by non-editors)
+-----------------------------------------
For new PRs, anyone with permission may perform gardening tasks.
The [Go wiki] sumarizes "gardening" as:
@@ -106,6 +106,226 @@ 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.
+
+1. Are the changes *for all XEPs* purely editorial?
+
+ 1. Add the [Editorial Change] and [Ready to Merge] labels.
+ 2. Stop.
+
+2. 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. Put the PR in the [Council Tracking] project.
+ 3. (Optionally, continue here with submitting the PR to Council via Trello
+ and move it right to the "On the agenda" column.)
+ 4. Stop.
+
+2. Is the XEP in Experimental state and the PR opener is not an author of the
+ XEP?
+
+ 1. If the issue has not been discussed on the standards list *or* if
+ the authors have not been involved in the discussion:
+
+ 1. Make sure the standards@ discussion (if it exists) is linked in the
+ PR.
+ 2. Add the [Needs Author] label.
+ 3. Put the PR in the [Author Tracking] project in the
+ "Not explicitly pinged" bin.
+ 4. Stop.
+
+3. Mark the PR as [Ready to Merge].
+
+
+Council Tracking
+----------------
+
+The [Council Tracking] project is used to track a PR through the Council
+approval process. The following columns are used:
+
+* On agenda: The PR has been added to the council trello and is awaiting
+ handling by Council.
+* Voting in progress: The PR has been discussed by council, but not everyone
+ has voted yet. Aside from exceptional circumstances, a PR can only reside
+ for at most two weeks in this column.
+
+ Note that council voting is veto-based and if someone did not vote, consent
+ is assumed. So a PR is rejected *iff* at least one person from council
+ explicitly voted against it.
+
+ When moving a PR into this column, make a comment on the PR which contains
+ the following information:
+
+ - The date at which the voting period started.
+ - Link to the respective meeting minutes.
+ - The date at which the voting period has ended or will end at latest.
+ - Possibly additional notes from the minutes, for example:
+
+ - "There will be additional discussion on standards@" (bonus points if
+ you add a link once the thread starts).
+ - "Two people will vote on-list after further consideration."
+
+* Done: The PR went through voting, but has not been merged yet. The
+ [Needs Council] label must be removed.
+
+ Add a comment with the result of the votes, possibly including links to
+ meeting minutes which contained the votes and on-list votes by the
+ respective council members.
+
+ If the PR was not vetoed, the [Ready to merge] label should be added.
+ Otherwise, the PR should be closed.
+
+ In any case, the PR can be removed from [Council Tracking] now.
+
+If a card awaits triaging, add it to the [Council Trello] in the first column
+*under* the "Find Minutes taker". Put the PR in the "On agenda" column (in the
+[Council Tracking], not the [Council Trello]).
+
+
+Author Tracking
+---------------
+
+This is less formal and more a tool for the editors to keep track of at which
+stage of escalation we are when getting in contact with the Authors. The
+columns should be self-explaining.
+
+Use your gut feeling on how long you wait for an authors reaction, but giving
+them at least a week on each stage seems reasonable.
+
+When an author replies and a discussion starts, move the PR to "Discussion in
+progress" and remember to check back once in a while if the discussion
+resolved.
+
+
+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
-------------
@@ -115,28 +335,27 @@ New ProtoXEPs
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 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.
-- Merge the PR and add a link to the generated protoxep (does this happen
- automatically yet?) to the card so that council can read it.
-- Wait for the XEP to appear on xmpp.org and then log into the webserver, change
- directories to `/home/xsf/xmpp-hg/extensions`, perform an `hg pull && hg
- update` (yes, that's right) and run `inxep.py name approvingbody` (eg.
- `./inxep.py pars council`).
+ Agendums" and add the PR to the [Council Tracking].
+- 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".
+ inform the author of the councils decision). Otherwise, see
+ "Promoting a ProtoXEP".
Promoting a ProtoXEP
--------------------
-- Once the council approves a ProtoXEP, move it out of the inbox and into the
+- 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
@@ -144,10 +363,9 @@ Promoting a ProtoXEP
- 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`.
-- Archive the first version of the XEP (TODO: this process is currently
- changing; add a description when the dust has settled).
-- Wait for the XEP to be published then log into the webserver and run
- `announce.py` (TODO: Add an example here).
+- 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
@@ -165,13 +383,64 @@ 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].
+
+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
+[Council Tracking]: https://github.com/xsf/xeps/projects/1
+[Author Tracking]: https://github.com/xsf/xeps/projects/2
+[Needs List Discussion]: https://github.com/xsf/xeps/labels/Needs%20List%20Discussion
+[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
[modeline]: # ( vim: set fenc=utf-8 ff=unix spell spl=en textwidth=80: )