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 documents can be found here:
Please use this repository to raise issues and submit pull requests:
For in-depth technical discussion, please post to the email@example.com email list:
To submit a new proposal for consideration as a XEP, please read this page:
XEP-0001: XMPP Extension Protocols defines the standards process followed by the XMPP Standards Foundation.
To build a single XEP as HTML simply run:
To build PDFs, you’ll need to install TeXML (probably in a Python 2 virtual environment). You can then build PDFs with:
To change the output directory, set the variable
OUTDIR=/tmp/xeps make all
For more information try
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
(serves on http://localhost:3080), and to stop/delete it afterwards
For new PRs, anyone with permission may perform gardening tasks. The Go wiki sumarizes “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
is:open is:pr no:assignee
To triage new issues or PRs:
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.
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.
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.
Is the PR a ProtoXEP?
Are the changes for all XEPs purely editorial?
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.)
Is the XEP in Experimental state and the PR opener is not an author of the XEP?
Mark the PR as Ready to Merge.
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):
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
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.
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:
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
switch prevents the tool from actually sending emails):
$ ./tools/send-updates.py --dry-run tools/old-xeplist.xml build/xeplist.xml firstname.lastname@example.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
$ ./tools/send-updates.py tools/old-xeplist.xml build/xeplist.xml email@example.com
A few tips:
firstname.lastname@example.org your own address.
--helpfor more information and ask jonasw/@horazont if things are still unclear.
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
Don’t forget to commit & push the changes to xep-attic.
inbox/tree and has a name that does not start with “xep-” (you may change this or ask the author to change it).
0.0.1and the status is
ProtoXEP(you may fix this or ask the author to fix it).
<number/>element in the XML file to match.
0.1and the initials to
XEP Editor: xyz(replacing “xyz” with your own initials).
<interim/>element from the XML file if it is included.
Ensure that the following sections exist (if not, ask the author to add them before promoting the XEP):
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.
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
To get a list of XEPs which need to be deferred (without changing anything), run:
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
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”.
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:
Create a new branch off master called
feature/xep-1234 (if the PR
touches multiple XEPs, I call it
Merge all Ready to Merge PRs which affect the XEP(s) into that branch.
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.)
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.)
If the build passes, check that the generated files look sane by running the docker container.
Merge the PR into master. If you are working on independent changes to multiple XEPs, you can merge them all in one go.
If you merged multiple things into master, re-do the docker build check.
Go back to “General notes on making changes”.